{"action":"created","comment":{"url":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/comments/23178152","id":23178152,"diff_hunk":"@@ -25,15 +25,73 @@ def valid_credentials?\n       true\n     end\n \n-    # API Requirements for Implementors\n+    # Fulfill an order.\n+    #\n+    # @example\n+    #\n+    #     carrier = ActiveFulfillment::Carrier.new(...)\n+    #     response = carrier.fulfill(order.id, order.shipping_address, order.line_items)\n+    #     assert response.success?\n+    #\n+    #\n+    # @param order_id [String] Unique identifier for the order\n+    # @param shipping_address [?] The address to ship the order to\n+    # @param line_items [?] The line items to include in the order.\n+    # @param options [Hash] Service-specific options.\n+    #\n+    # @return [ActiveFulfillment::FulfillResponse]\n+    # @note This should be implemented by concrete subclasses.\n     def fulfill(order_id, shipping_address, line_items, options = {})\n       raise NotImplementedError.new(\"Subclasses must implement\")\n     end\n \n-    def fetch_stock_levels(options = {})\n+    # Retrieve stock levels for a single SKU that the fulfillment service stocks.\n+    # The stock levels will be returned as a Hash-like object, indexed by SKU.\n+    #\n+    # @param sku [Array<String>] The SKUs to retreive. All the provided skus\n+    #   must be set as a key in the response object.\n+    # @param options [Hash] Service-specific options.\n+    # @return [ActiveFulfillment::StockLevelResponse]\n+    # @note This should be implemented by concrete subclasses.\n+    def fetch_stock_levels(skus, options = {})\n+      fetch_all_stock_levels(options)\n+    end\n+\n+    # Retrieve stock levels for all SKUs that the fulfillment service stocks.\n+    # The stock levels will be returned as a Hash-like object, indexed by SKU.\n+    #\n+    # @example\n+    #\n+    #     carrier = ActiveFulfillment::Carrier.new(...)\n+    #     stock_levels = carrier.fetch_all_stock_levels\n+    #     stock_levels.each { |sku, stock| ... }\n+    #\n+    # @param options [Hash] Service-specific options.\n+    # @return [ActiveFulfillment::StockLevelResponse]\n+    # @note This should be implemented by concrete subclasses.\n+    def fetch_all_stock_levels(options = {})\n+      raise NotImplementedError.new(\"Subclasses must implement\")\n+    end\n+\n+    # Method to retrieve tracking data for a list of orders.\n+    #\n+    # @example\n+    #\n+    #     carrier = ActiveFulfillment::Carrier.new(...)\n+    #     tracking_data = carrier.fetch_tracking_data([order.id])\n+    #     tracking_data['order_id'].tracking_code\n+    #     tracking_data['order_id'].tracking_url\n+    #     tracking_data['order_id'].company\n+    #\n+    # @param options [Array<String>] A list of order IDs for which to retrieve tracking options.\n+    # @param options [Hash] Service-specific options.\n+    # @return [ActiveFulfillment::TrackingDataResponse]\n+    # @note This should be implemented by concrete subclasses.\n+    def fetch_tracking_data(order_ids, options = {})","path":"lib/active_fulfillment/service.rb","position":68,"original_position":68,"commit_id":"56068d84b1f1f29bd198ca5ac92b73ca08310ced","original_commit_id":"56068d84b1f1f29bd198ca5ac92b73ca08310ced","user":{"login":"wvanbergen","id":15870,"avatar_url":"https://avatars.githubusercontent.com/u/15870?v=3","gravatar_id":"","url":"https://api.github.com/users/wvanbergen","html_url":"https://github.com/wvanbergen","followers_url":"https://api.github.com/users/wvanbergen/followers","following_url":"https://api.github.com/users/wvanbergen/following{/other_user}","gists_url":"https://api.github.com/users/wvanbergen/gists{/gist_id}","starred_url":"https://api.github.com/users/wvanbergen/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/wvanbergen/subscriptions","organizations_url":"https://api.github.com/users/wvanbergen/orgs","repos_url":"https://api.github.com/users/wvanbergen/repos","events_url":"https://api.github.com/users/wvanbergen/events{/privacy}","received_events_url":"https://api.github.com/users/wvanbergen/received_events","type":"User","site_admin":false},"body":"do we also want to add `fetch_all_tracking_data(options =  {})` ?","created_at":"2015-01-19T18:35:12Z","updated_at":"2015-01-19T18:35:12Z","html_url":"https://github.com/Shopify/active_fulfillment/pull/53#discussion_r23178152","pull_request_url":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/53","_links":{"self":{"href":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/comments/23178152"},"html":{"href":"https://github.com/Shopify/active_fulfillment/pull/53#discussion_r23178152"},"pull_request":{"href":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/53"}}},"pull_request":{"url":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/53","id":27626904,"html_url":"https://github.com/Shopify/active_fulfillment/pull/53","diff_url":"https://github.com/Shopify/active_fulfillment/pull/53.diff","patch_url":"https://github.com/Shopify/active_fulfillment/pull/53.patch","issue_url":"https://api.github.com/repos/Shopify/active_fulfillment/issues/53","number":53,"state":"open","locked":false,"title":"API proposal","user":{"login":"wvanbergen","id":15870,"avatar_url":"https://avatars.githubusercontent.com/u/15870?v=3","gravatar_id":"","url":"https://api.github.com/users/wvanbergen","html_url":"https://github.com/wvanbergen","followers_url":"https://api.github.com/users/wvanbergen/followers","following_url":"https://api.github.com/users/wvanbergen/following{/other_user}","gists_url":"https://api.github.com/users/wvanbergen/gists{/gist_id}","starred_url":"https://api.github.com/users/wvanbergen/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/wvanbergen/subscriptions","organizations_url":"https://api.github.com/users/wvanbergen/orgs","repos_url":"https://api.github.com/users/wvanbergen/repos","events_url":"https://api.github.com/users/wvanbergen/events{/privacy}","received_events_url":"https://api.github.com/users/wvanbergen/received_events","type":"User","site_admin":false},"body":"Here's my proposal to make the API more consistent and well defined. I added yardoc comments to make the types more explicit.\r\n\r\n@pickle27 for review/discussion.","created_at":"2015-01-19T18:32:25Z","updated_at":"2015-01-19T18:35:12Z","closed_at":null,"merged_at":null,"merge_commit_sha":"5be80b1d73df285abac39b25de07288e15410517","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/53/commits","review_comments_url":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/53/comments","review_comment_url":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/comments/{number}","comments_url":"https://api.github.com/repos/Shopify/active_fulfillment/issues/53/comments","statuses_url":"https://api.github.com/repos/Shopify/active_fulfillment/statuses/56068d84b1f1f29bd198ca5ac92b73ca08310ced","head":{"label":"Shopify:change_api","ref":"change_api","sha":"56068d84b1f1f29bd198ca5ac92b73ca08310ced","user":{"login":"Shopify","id":8085,"avatar_url":"https://avatars.githubusercontent.com/u/8085?v=3","gravatar_id":"","url":"https://api.github.com/users/Shopify","html_url":"https://github.com/Shopify","followers_url":"https://api.github.com/users/Shopify/followers","following_url":"https://api.github.com/users/Shopify/following{/other_user}","gists_url":"https://api.github.com/users/Shopify/gists{/gist_id}","starred_url":"https://api.github.com/users/Shopify/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Shopify/subscriptions","organizations_url":"https://api.github.com/users/Shopify/orgs","repos_url":"https://api.github.com/users/Shopify/repos","events_url":"https://api.github.com/users/Shopify/events{/privacy}","received_events_url":"https://api.github.com/users/Shopify/received_events","type":"Organization","site_admin":false},"repo":{"id":16508,"name":"active_fulfillment","full_name":"Shopify/active_fulfillment","owner":{"login":"Shopify","id":8085,"avatar_url":"https://avatars.githubusercontent.com/u/8085?v=3","gravatar_id":"","url":"https://api.github.com/users/Shopify","html_url":"https://github.com/Shopify","followers_url":"https://api.github.com/users/Shopify/followers","following_url":"https://api.github.com/users/Shopify/following{/other_user}","gists_url":"https://api.github.com/users/Shopify/gists{/gist_id}","starred_url":"https://api.github.com/users/Shopify/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Shopify/subscriptions","organizations_url":"https://api.github.com/users/Shopify/orgs","repos_url":"https://api.github.com/users/Shopify/repos","events_url":"https://api.github.com/users/Shopify/events{/privacy}","received_events_url":"https://api.github.com/users/Shopify/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/Shopify/active_fulfillment","description":"Active Merchant library for integration with order fulfillment services","fork":false,"url":"https://api.github.com/repos/Shopify/active_fulfillment","forks_url":"https://api.github.com/repos/Shopify/active_fulfillment/forks","keys_url":"https://api.github.com/repos/Shopify/active_fulfillment/keys{/key_id}","collaborators_url":"https://api.github.com/repos/Shopify/active_fulfillment/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/Shopify/active_fulfillment/teams","hooks_url":"https://api.github.com/repos/Shopify/active_fulfillment/hooks","issue_events_url":"https://api.github.com/repos/Shopify/active_fulfillment/issues/events{/number}","events_url":"https://api.github.com/repos/Shopify/active_fulfillment/events","assignees_url":"https://api.github.com/repos/Shopify/active_fulfillment/assignees{/user}","branches_url":"https://api.github.com/repos/Shopify/active_fulfillment/branches{/branch}","tags_url":"https://api.github.com/repos/Shopify/active_fulfillment/tags","blobs_url":"https://api.github.com/repos/Shopify/active_fulfillment/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/Shopify/active_fulfillment/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/Shopify/active_fulfillment/git/refs{/sha}","trees_url":"https://api.github.com/repos/Shopify/active_fulfillment/git/trees{/sha}","statuses_url":"https://api.github.com/repos/Shopify/active_fulfillment/statuses/{sha}","languages_url":"https://api.github.com/repos/Shopify/active_fulfillment/languages","stargazers_url":"https://api.github.com/repos/Shopify/active_fulfillment/stargazers","contributors_url":"https://api.github.com/repos/Shopify/active_fulfillment/contributors","subscribers_url":"https://api.github.com/repos/Shopify/active_fulfillment/subscribers","subscription_url":"https://api.github.com/repos/Shopify/active_fulfillment/subscription","commits_url":"https://api.github.com/repos/Shopify/active_fulfillment/commits{/sha}","git_commits_url":"https://api.github.com/repos/Shopify/active_fulfillment/git/commits{/sha}","comments_url":"https://api.github.com/repos/Shopify/active_fulfillment/comments{/number}","issue_comment_url":"https://api.github.com/repos/Shopify/active_fulfillment/issues/comments/{number}","contents_url":"https://api.github.com/repos/Shopify/active_fulfillment/contents/{+path}","compare_url":"https://api.github.com/repos/Shopify/active_fulfillment/compare/{base}...{head}","merges_url":"https://api.github.com/repos/Shopify/active_fulfillment/merges","archive_url":"https://api.github.com/repos/Shopify/active_fulfillment/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/Shopify/active_fulfillment/downloads","issues_url":"https://api.github.com/repos/Shopify/active_fulfillment/issues{/number}","pulls_url":"https://api.github.com/repos/Shopify/active_fulfillment/pulls{/number}","milestones_url":"https://api.github.com/repos/Shopify/active_fulfillment/milestones{/number}","notifications_url":"https://api.github.com/repos/Shopify/active_fulfillment/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/Shopify/active_fulfillment/labels{/name}","releases_url":"https://api.github.com/repos/Shopify/active_fulfillment/releases{/id}","created_at":"2008-05-13T15:04:36Z","updated_at":"2015-01-17T19:43:07Z","pushed_at":"2015-01-19T18:31:05Z","git_url":"git://github.com/Shopify/active_fulfillment.git","ssh_url":"git@github.com:Shopify/active_fulfillment.git","clone_url":"https://github.com/Shopify/active_fulfillment.git","svn_url":"https://github.com/Shopify/active_fulfillment","homepage":"http://shopify.github.io/active_fulfillment","size":1234,"stargazers_count":86,"watchers_count":86,"language":"Ruby","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":36,"mirror_url":null,"open_issues_count":5,"forks":36,"open_issues":5,"watchers":86,"default_branch":"master"}},"base":{"label":"Shopify:master","ref":"master","sha":"4312da80c596cfbb05b77e33fabe7ae2981e37c1","user":{"login":"Shopify","id":8085,"avatar_url":"https://avatars.githubusercontent.com/u/8085?v=3","gravatar_id":"","url":"https://api.github.com/users/Shopify","html_url":"https://github.com/Shopify","followers_url":"https://api.github.com/users/Shopify/followers","following_url":"https://api.github.com/users/Shopify/following{/other_user}","gists_url":"https://api.github.com/users/Shopify/gists{/gist_id}","starred_url":"https://api.github.com/users/Shopify/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Shopify/subscriptions","organizations_url":"https://api.github.com/users/Shopify/orgs","repos_url":"https://api.github.com/users/Shopify/repos","events_url":"https://api.github.com/users/Shopify/events{/privacy}","received_events_url":"https://api.github.com/users/Shopify/received_events","type":"Organization","site_admin":false},"repo":{"id":16508,"name":"active_fulfillment","full_name":"Shopify/active_fulfillment","owner":{"login":"Shopify","id":8085,"avatar_url":"https://avatars.githubusercontent.com/u/8085?v=3","gravatar_id":"","url":"https://api.github.com/users/Shopify","html_url":"https://github.com/Shopify","followers_url":"https://api.github.com/users/Shopify/followers","following_url":"https://api.github.com/users/Shopify/following{/other_user}","gists_url":"https://api.github.com/users/Shopify/gists{/gist_id}","starred_url":"https://api.github.com/users/Shopify/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Shopify/subscriptions","organizations_url":"https://api.github.com/users/Shopify/orgs","repos_url":"https://api.github.com/users/Shopify/repos","events_url":"https://api.github.com/users/Shopify/events{/privacy}","received_events_url":"https://api.github.com/users/Shopify/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/Shopify/active_fulfillment","description":"Active Merchant library for integration with order fulfillment services","fork":false,"url":"https://api.github.com/repos/Shopify/active_fulfillment","forks_url":"https://api.github.com/repos/Shopify/active_fulfillment/forks","keys_url":"https://api.github.com/repos/Shopify/active_fulfillment/keys{/key_id}","collaborators_url":"https://api.github.com/repos/Shopify/active_fulfillment/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/Shopify/active_fulfillment/teams","hooks_url":"https://api.github.com/repos/Shopify/active_fulfillment/hooks","issue_events_url":"https://api.github.com/repos/Shopify/active_fulfillment/issues/events{/number}","events_url":"https://api.github.com/repos/Shopify/active_fulfillment/events","assignees_url":"https://api.github.com/repos/Shopify/active_fulfillment/assignees{/user}","branches_url":"https://api.github.com/repos/Shopify/active_fulfillment/branches{/branch}","tags_url":"https://api.github.com/repos/Shopify/active_fulfillment/tags","blobs_url":"https://api.github.com/repos/Shopify/active_fulfillment/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/Shopify/active_fulfillment/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/Shopify/active_fulfillment/git/refs{/sha}","trees_url":"https://api.github.com/repos/Shopify/active_fulfillment/git/trees{/sha}","statuses_url":"https://api.github.com/repos/Shopify/active_fulfillment/statuses/{sha}","languages_url":"https://api.github.com/repos/Shopify/active_fulfillment/languages","stargazers_url":"https://api.github.com/repos/Shopify/active_fulfillment/stargazers","contributors_url":"https://api.github.com/repos/Shopify/active_fulfillment/contributors","subscribers_url":"https://api.github.com/repos/Shopify/active_fulfillment/subscribers","subscription_url":"https://api.github.com/repos/Shopify/active_fulfillment/subscription","commits_url":"https://api.github.com/repos/Shopify/active_fulfillment/commits{/sha}","git_commits_url":"https://api.github.com/repos/Shopify/active_fulfillment/git/commits{/sha}","comments_url":"https://api.github.com/repos/Shopify/active_fulfillment/comments{/number}","issue_comment_url":"https://api.github.com/repos/Shopify/active_fulfillment/issues/comments/{number}","contents_url":"https://api.github.com/repos/Shopify/active_fulfillment/contents/{+path}","compare_url":"https://api.github.com/repos/Shopify/active_fulfillment/compare/{base}...{head}","merges_url":"https://api.github.com/repos/Shopify/active_fulfillment/merges","archive_url":"https://api.github.com/repos/Shopify/active_fulfillment/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/Shopify/active_fulfillment/downloads","issues_url":"https://api.github.com/repos/Shopify/active_fulfillment/issues{/number}","pulls_url":"https://api.github.com/repos/Shopify/active_fulfillment/pulls{/number}","milestones_url":"https://api.github.com/repos/Shopify/active_fulfillment/milestones{/number}","notifications_url":"https://api.github.com/repos/Shopify/active_fulfillment/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/Shopify/active_fulfillment/labels{/name}","releases_url":"https://api.github.com/repos/Shopify/active_fulfillment/releases{/id}","created_at":"2008-05-13T15:04:36Z","updated_at":"2015-01-17T19:43:07Z","pushed_at":"2015-01-19T18:31:05Z","git_url":"git://github.com/Shopify/active_fulfillment.git","ssh_url":"git@github.com:Shopify/active_fulfillment.git","clone_url":"https://github.com/Shopify/active_fulfillment.git","svn_url":"https://github.com/Shopify/active_fulfillment","homepage":"http://shopify.github.io/active_fulfillment","size":1234,"stargazers_count":86,"watchers_count":86,"language":"Ruby","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":36,"mirror_url":null,"open_issues_count":5,"forks":36,"open_issues":5,"watchers":86,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/53"},"html":{"href":"https://github.com/Shopify/active_fulfillment/pull/53"},"issue":{"href":"https://api.github.com/repos/Shopify/active_fulfillment/issues/53"},"comments":{"href":"https://api.github.com/repos/Shopify/active_fulfillment/issues/53/comments"},"review_comments":{"href":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/53/comments"},"review_comment":{"href":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/Shopify/active_fulfillment/pulls/53/commits"},"statuses":{"href":"https://api.github.com/repos/Shopify/active_fulfillment/statuses/56068d84b1f1f29bd198ca5ac92b73ca08310ced"}}}}