Orders Service Description

The following methods are available at the servlet path /rest/1.3/orders
GET  /1.3/orders/schema
Returns the XML Schema that describes the format of the retrieved data when the Orders Service API calls are made.

Supported Output Types : application/xml

GET  /1.3/orders/{receipt}
Returns a list of order detail objects which match the given receipt.

Return Type: List of OrderDatas

Request Parameters :

NameRequiredDescription
skufalsesku/itemNo of the line item. Used to identify individual purchase in multi-item cart purchase

Supported Output Types : application/xml, application/json, text/csv

Required Roles : api_order_read, HAS_DEVELOPER_KEY

GET  /1.3/orders/{receipt}/upsells
Returns all the upsell transactions for the given parent upsell transaction.
If the transaction does not exist, or the user does not have access to the transaction, or if there are no upsells for this transaction, a status code of 403 (No Content) will be returned.

Return Type: List of OrderDatas

Supported Output Types : application/xml, application/json, text/csv

Required Roles : api_order_read, HAS_DEVELOPER_KEY

POST  /1.3/orders/{receipt}/reinstate
*BETA* Allows a vendor to restart a cancelled subscription

Return Type: No Content

Request Parameters :

NameRequiredDescription
skufalseThe item number of the subscription product that should be reinstated for the order

Required Roles : HAS_DEVELOPER_KEY, api_subscription_modifications

POST  /1.3/orders/{receipt}/pause
*BETA* Allows a vendor to change the rebill date of a subscription

Return Type: No Content

Request Parameters :

NameRequiredDescription
restartDatetrueThe date when the subscription will be resumed in format yyyy-mm-dd
skufalseThe item number of the subscription product that should be reinstated for the order

Required Roles : HAS_DEVELOPER_KEY, api_subscription_modifications

POST  /1.3/orders/{receipt}/extend
*BETA* Allows a vendor to extend a subscription by a given number of rebill periods

Return Type: No Content

Request Parameters :

NameRequiredDescription
numPeriodstrueThe number of periods to extend the subscription by
skufalsesku/itemNo of the line item. Used to identify individual purchase in multi-item cart purchase

Required Roles : HAS_DEVELOPER_KEY, api_subscription_modifications

POST  /1.3/orders/{receipt}/changeProduct
*BETA* Allows a vendor to change (upgrade or downgrade) the product associated with a subscription.

Return Type: No Content

Request Parameters :

NameRequiredDescription
oldSkutrueThe SKU of the current product for the subscription.
newSkutrueThe SKU of the new product for the subscription.
carryAffiliatefalseDetermines if the affiliate from the original transaction is carried over to the new subscription.
applyProratedRefundfalseDetermines if the prorated refund should be applied on the product change. This parameter will default to TRUE if not explicitly set
applyProratedRefundfalseDetermines if the prorated refund should be applied on the product change. This parameter will default to TRUE if not explicitly set
nextRebillDatefalseAllows the vendor to change the date of the next rebill. Date Format is YYYY-MM-DD. Not passing in any value will set the next rebill date to the next day of product change

Required Roles : HAS_DEVELOPER_KEY, api_order_write, api_subscription_modifications

POST  /1.3/orders/{receipt}/changeAddress
Allows a vendor to change shipping address of a physical recurring subscription.

Return Type: No Content

Request Parameters :

NameRequiredDescription
firstNamefalseUpdated customer first name.
lastNamefalseUpdated customer last name.
address1trueUpdated address (line 1).
address2falseUpdated address (line 2).
citytrueUpdated city.
countyfalseUpdated county.
provincefalseUpdated state or province.
countryCodetrueUpdated country code.
postalCodefalseUpdated postal code or Zip.

Required Roles : HAS_DEVELOPER_KEY, api_order_write

GET  /1.3/orders/count
Same as the list command, except that this one returns the count of the orders returned based on the search criteria.

Return Type: Count of matching orders

Request Parameters :

NameRequiredDescription
startDatefalseThe beginning date for the search (yyyy-mm-dd)
endDatefalseThe end date for the search (yyyy-mm-dd)
typefalseThe type of transactions to be returned. Supported types are [SALE / RFND / CGBK / FEE / BILL / TEST_SALE / TEST_BILL / TEST_RFND / TEST_FEE].
If not specified all types will be returned. If an invalid type is specified, no transactions will be returned.
vendorfalseThe vendor name. Supports wildcard searches using the '%' character. (Wildcards are converted to %25 after url encoding is done by the client)
affiliatefalseThe affiliate name. Supports the word 'none' to search for transactions without affiliates, and wildcard searches using the '%' character. (Wilcards are converted to %25 after url encoding is done by the client)
lastNamefalseCustomers last name. Supports wildcard searches using the '%' character. (Wildcards are converted to %25 after url encoding is done by the client)
emailfalseThe email of the customer. Supports wildcard searches using the '%' character. (Wildcards are converted to %25 after url encoding is done by the client)
tidfalseThe TID (Tracking ID / Promo Code) to search on. This will search both vendor and affiliate tracking codes and be returned in the promo field
rolefalseRole account was of transaction options are [VENDOR, AFFILIATE]

Required Roles : api_order_read, HAS_DEVELOPER_KEY

GET  /1.3/orders/list
List orders for the authenticated user scoped to the search criteria. Only the first 100 orders will be returned. This method supports pagination, so if the second page of the next 100 items is required a request header 'Page' with value 2 will return them.

This method will return 200 if all the receipts have been obtained, or a 206 [Partial Return] if there are more results available.

Return Type: List of OrderDatas

Request Parameters :

NameRequiredDescription
startDatefalseThe beginning date for the search (yyyy-mm-dd). If a startDate is specified, you must also specify an endDate.
endDatefalseThe end date for the search (yyyy-mm-dd). If an endDate is specified, you must also specify a startDate.
typefalseThe type of transactions to be returned. Supported types are [SALE / RFND / CGBK / FEE / BILL / TEST_SALE / TEST_BILL / TEST_RFND /TEST_FEE].
If not specified all types will be returned. If an invalid type is specified, no transactions will be returned.
vendorfalseThe vendor name. Supports wildcard searches using the '%' character. (Wildcards are converted to %25 after url encoding is done by the client)
affiliatefalseThe affiliate name. Supports the word 'none' to search for transactions without affiliates, and wildcard searches using the '%' character. (Wilcards are converted to %25 after url encoding is done by the client)
lastNamefalseCustomers last name. Supports wildcard searches using the '%' character. (Wildcards are converted to %25 after url encoding is done by the client)
itemfalseThe item number of the order
emailfalseThe email of the customer. Supports wildcard searches using the '%' character. (Wildcards are converted to %25 after url encoding is done by the client)
tidfalseThe TID (Tracking ID / Promo Code) to search on. This will search both vendor and affiliate tracking codes and be returned in the promo field
rolefalseRole account was of transaction options are [VENDOR, AFFILIATE]
postalCodefalseCustomer's zip or postal code. Supports wildcard searches.
amountfalseThe transaction total amount

Supported Output Types : application/xml, application/json, text/csv

Required Roles : api_order_read, HAS_DEVELOPER_KEY

HEAD  /1.3/orders/{receipt}
This head request is used to identify if a particular order or a subscription is active, i.e. it has not been refunded, chargebacked or cancelled. It will return a 403 (Forbidden) if that's the case, or a 204 if the order is still active. Note that it will also return a 403 if the order is not found, or the user does not have access to that receipt.
In addition, head request on a rebill transaction will return the status of that particular rebill, not of the original transaction which may be different. It is advisable to use head requests only on the parent transactions.

Return Type:  -

Request Parameters :

NameRequiredDescription
skufalsesku/itemNo of the line item. Used to identify individual purchase in multi-item cart purchase

Supported Output Types : application/xml, application/json, text/csv

Required Roles : api_order_read, HAS_DEVELOPER_KEY