/orders
Overview
This article provides information about the /orders endpoint of the FastSpring API.
Use the /orders API endpoint to retrieve information about a single order or retrieve a list of multiple orders matching a set of criteria.
You can retrieve orders by order ID, product path, or date range. You can optionally combine parameters in your request, for example, retrieving all orders for a particular product that occurred in a given date range.
When retrieving multiple orders, the API paginates the response with a limit of 50 records per page by default. To assist with paging through the results, you can optionally specify a custom limit to the number of records per page, and the desired page number in your request.
Get Orders
Request Parameters
Parameter | Values | Description |
---|---|---|
begin | yyyy-mm-dd | filters results to include transactions after the specified begin date (must be at least one day before the specified end date) |
end | yyyy-mm-dd | filters results to include transactions before the specified end date |
limit | integer | integer limits the number of order records returned per page (default is 50 records) |
page | integer | specifies page number of results to be returned; used together with limit to control pagination |
products | string | filters results to include only transactions involving the specified product ID(s) / product path(s) |
rebill | true/false | filters results to include only subscription rebill transactions or exclude all subscription rebill transactions |
returns | true/false | filters results to include orders with or without returns; response includes returns array with return IDs where applicable |
scope | all, live, test | filters results to include live transactions, test transactions, or both |
status | completed, canceled, failed | filters results by transaction status; "completed" = successful orders, "canceled" = declined orders, "failed" = transaction failed to complete (very uncommon) |
Examples
Example 1: Get orders by ID
GET /orders/{id1},{id2},{id3},...
Note
{ "order": "oN5eASPKTM2Jwkx15ICNyg", // internal order ID "id": "oN5eASPKTM2Jwkx15ICNyg", // backward compatibility "reference": "FUR191015-1265-35113", // customer-facing order reference "buyerReference": null, // optional purchase order number entered by the customer "ipAddress": "000.000.00.000", // the buyer's apparent IP address "completed": true, // false if order failed, was declined, or is pending "changed": 1571172709980, // date of the most recent update to this order record, in milliseconds "changedValue": 1571172709980, // date of the most recent update to this order record, in milliseconds (backward compatibility) "changedInSeconds": 1571172709, // date of the most recent update to this order record, in seconds "changedDisplay": "10/15/19", // date of the most recent update to this order record, formatted for display based on the language in which the order was processed, as selected by the customer "language": "en", // ISO 2-character language code for the language in which the order was processed, as selected by the customer "live": false, // true if not a test order "currency": "USD", "payoutCurrency": "USD", "invoiceUrl": "https://yourexamplestore.onfastspring.com/account/order/YES191015-1265-35113/invoice", "account": "N8FjcSWcQNeYCc-suM1O8g", // FastSpring-generated customer account ID "total": 36.15, "totalDisplay": "$36.15", "totalInPayoutCurrency": 36.15, "totalInPayoutCurrencyDisplay": "$36.15", "tax": 0.0, "taxDisplay": "$0.00", "taxInPayoutCurrency": 0.0, "taxInPayoutCurrencyDisplay": "$0.00", "subtotal": 36.15, "subtotalDisplay": "$36.15", "subtotalInPayoutCurrency": 36.15, "subtotalInPayoutCurrencyDisplay": "$36.15", "discount": 0.0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0.0, "discountInPayoutCurrencyDisplay": "$0.00", "discountWithTax": 0.0, "discountWithTaxDisplay": "$0.00", "discountWithTaxInPayoutCurrency": 0.0, "discountWithTaxInPayoutCurrencyDisplay": "$0.00", "billDescriptor": "FS* YOUREXAMPLESTORE", "payment": { "type": "test", // payment method: "paypal", "amazon", "creditcard", "test", "bank", "alipay", "purchase-order", "free" "creditCard": "visa", // ONLY appears when "type" = "creditcard". Values = "visa", "mastercard", "amex", "discover", "jcb", "carteblanche", "dinersclub", "unionpay" "cardEnding": "4242", // ONLY appears when "type" = "creditcard". Last four digits of the card number "bank": "sofort" // ONLY appears when "type" = "bank". Values = "wire", "brazilwire", "ideal", "giropay", "sofort", "ecard", "sepa", "alipay" }, "customer": { "first": "Leeroy", "last": "Jenkins", "email": "ne1@all.com", "company": null, "phone": null }, "address": { "addressLine1": "801 Garden St.", // for physical product purchase or when Storefront is configured to force collection "city": "Santa Barbara", "regionCode": "CA", // US orders only; ISO 2-character state code; only appears for physical product purchase or when Storefront is configured to force collection "regionDisplay": "California", // state or region of the address, formatted for display "region": "California", // for physical product purchase or when Storefront is configured to force collection "postalCode": "93101", "country": "US", "display": "Santa Barbara, California, 93101, US" }, "recipients": [ { "recipient": { "first": "Leeroy", "last": "Jenkins", "email": "ne1@all.com", "company": null, "phone": null, "account": "N8FjcSWcQNeYCc-suM1O8g", "address": { "city": "Santa Barbara", "regionCode": "CA", "regionDisplay": "California", "region": "California", "postalCode": "93101", "country": "US", "display": "Santa Barbara, California, 93101, US" } } } ], "notes": [], "items": [ { "product": "example-monthly-subscription", "quantity": 1, "display": "Example Monthly Subscription", "sku": "exsub1", "subtotal": 14.95, "subtotalDisplay": "$14.95", "subtotalInPayoutCurrency": 14.95, "subtotalInPayoutCurrencyDisplay": "$14.95", "attributes": { "CustomAttribute1": "CustomValue1", // key and value are defined under Products > More > Custom Attributes (Advanced) "CustomAttribute2": "CustomValue2", // key and value are defined under Products > More > Custom Attributes (Advanced) "key": "value" // key and value are defined under Products > More > Custom Attributes (Advanced) }, "discount": 0.0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0.0, "discountInPayoutCurrencyDisplay": "$0.00", "coupon": "FREE", // coupon code (not coupon path / ID) applied to the current order item (ONLY appears when applicable) "subscription": "73lsX5kvRsWKLzwRNMkcow", // FastSpring-generated subscription ID for the subscription associated with the current item "fulfillments": { "example-monthly-subscription_file_0": [ { "display": "EXAMPLE.exe", "size": 129, "file": "https://yourexamplestore.onfastspring.com/account/file/YES191015-1265-46134F", "type": "file" } ], "example-monthly-subscription_license_1": [ { "license": "s5cMEOpM0zP5KQqD5Wps", "display": "License Key", "type": "license" } ], "instructions": "Thank you for subscribing to Example Monthly Subscription." } }, { "product": "example-product-2", "quantity": 1, "display": "Example Product 2", "sku": "exprod2", "subtotal": 9.95, "subtotalDisplay": "$9.95", "subtotalInPayoutCurrency": 9.95, "subtotalInPayoutCurrencyDisplay": "$9.95", "discount": 0.0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0.0, "discountInPayoutCurrencyDisplay": "$0.00", "coupon": "FREE", // coupon code (not coupon path / ID) applied to the current order item (ONLY appears when applicable) "fulfillments": { "example-product-2_license_0": [ { "license": "ejTUv8dpuJWZQ5lMN6YE", "display": "License Key", "type": "license" } ], "example-product-2_file_1": [ { "display": "EXAMPLE2.exe", "size": 5769, "file": "https://yourexamplestore.onfastspring.com/account/file/YES191015-1265-67116F", "type": "file" } ] }, "driver": { // when the current order item is linked to another item (e.g. offered as a cross-sell or a subscription addon), this describes that relationship and identifies the parent item "type": "addon", // current item's relationship to the parent item: "cross-sell", "options", "bundle", "configuration", "addon" or "one_time_fee" "path": "example-monthly-subscription" // product path / ID of the parent or triggering item } }, { "product": "example-monthly-subscription.setupFee", "quantity": 1, "display": "One-time Setup Fee", "sku": null, "subtotal": 10.0, "subtotalDisplay": "$10.00", "subtotalInPayoutCurrency": 10.0, "subtotalInPayoutCurrencyDisplay": "$10.00", "discount": 0.0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0.0, "discountInPayoutCurrencyDisplay": "$0.00", "coupon": "FREE", // coupon code (not coupon path / ID) applied to the current order item (ONLY appears when applicable) "fulfillments": {}, "driver": { // when the current order item is linked to another item (e.g. offered as a cross-sell or a subscription addon), this describes that relationship and identifies the parent item "type": "one_time_fee", // current item's relationship to the parent item: "cross-sell", "options", "bundle", "configuration", "addon" or "one_time_fee" "path": "example-monthly-subscription" // product path / ID of the parent or triggering item } }, { "product": "example-product-3", "quantity": 1, "display": "Example Product 3", "sku": "exprod3", "subtotal": 1.25, "subtotalDisplay": "$1.25", "subtotalInPayoutCurrency": 1.25, "subtotalInPayoutCurrencyDisplay": "$1.25", "attributes": { "conditions": "{exclude:{countries:['AT','GB']}}" }, "discount": 0.0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0.0, "discountInPayoutCurrencyDisplay": "$0.00", "coupon": "FREE", // coupon code (not coupon path / ID) applied to the current order item (ONLY appears when applicable) "fulfillments": { "example-product-3_file_1": [ { "display": "EXAMPLE3.exe", "size": 5769, "file": "https://yourexamplestore.onfastspring.com/account/file/YES191015-1265-14137F", "type": "file" } ], "instructions": "Thank you for purchasing Example Product 3. To register, please launch the trial version and select Help -> Register Example Product 3. Then, copy and paste the license key below into the License Key field and click Submit." }, "driver": { // when the current order item is linked to another item (e.g. offered as a cross-sell or a subscription addon), this describes that relationship and identifies the parent item "type": "cross-sell", // current item's relationship to the parent item: "cross-sell", "options", "bundle", "configuration", "addon" or "one_time_fee" "path": "example-monthly-subscription" // product path / ID of the parent or triggering item } } ] }
{ "orders": [ { "action": "order.get", "order": "zSprqRHITGeW0kSGC7AKmh", // order ID requested "result": "error", "error": { "order": "Not found" } } ] }
Get orders by product path
Example 2: Get orders by product path
GET /orders?products=product1,product2&limit=20&page=1
{ "action": "order.lookup", "result": "success", "page": 1, "limit": 20, "nextPage": 2, "total": 1006, "orders": [ { "order": "nlqoczuZSaGKzuNNK5IDiQ", "id": "nlqoczuZSaGKzuNNK5IDiQ", "reference": null, "buyerReference": null, "ipAddress": "000.000.00.000", "completed": false, "changed": 1471997419992, "changedValue": 1471997419992, "changedInSeconds": 1471997419, "changedDisplay": "8/24/16", "language": "en", "live": false, "currency": "USD", "account": "KJRTYQByS_WIcVQ-AZp6kw", "payoutCurrency": "USD", "invoiceUrl": "https://yourexamplestore.onfastspring.com/account/order/null/invoice", "total": 10, "totalDisplay": "$10.00", "totalInPayoutCurrency": 10, "totalInPayoutCurrencyDisplay": "$10.00", "tax": 0, "taxDisplay": "$0.00", "taxInPayoutCurrency": 0, "taxInPayoutCurrencyDisplay": "$0.00", "subtotal": 10, "subtotalDisplay": "$10.00", "subtotalInPayoutCurrency": 10, "subtotalInPayoutCurrencyDisplay": "$10.00", "discount": 0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "$0.00", "discountWithTax": 0, "discountWithTaxDisplay": "$0.00", "discountWithTaxInPayoutCurrency": 0, "discountWithTaxInPayoutCurrencyDisplay": "$0.00", "payment": {}, "customer": { "first": "New", "last": "Order", "email": "ne1@all.com", "company": null, "phone": "1234567890" }, "address": { "city": "Santa Barbara", "regionCode": "CA", "regionDisplay": "California", "region": "California", "postalCode": "93101", "country": "US", "display": "Santa Barbara, California, 93101, US" }, "recipients": [ { "recipient": { "first": "New", "last": "Order", "email": "ne1@all.com", "company": null, "phone": "1234567890", "account": "KJRTYQByS_WIcVQ-AZp6kw", "address": { "city": "Santa Barbara", "regionCode": "CA", "regionDisplay": "California", "region": "California", "postalCode": "93101", "country": "US", "display": "Santa Barbara, California, 93101, US" } } } ], "notes": [], "items": [ { "product": "suba", "quantity": 1, "display": "PaymentReminderBeforeUpdate", "sku": "SKU111", "subtotal": 10, "subtotalDisplay": "$10.00", "subtotalInPayoutCurrency": 10, "subtotalInPayoutCurrencyDisplay": "$10.00", "discount": 0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "$0.00", "subscription": "YDnZ-ExrQ3mWe0YTmSsQaQ" } ] } ... ] }
Get orders by date range
Example 3: Get orders by date range
GET /orders?begin=yyyy-mm-dd&end=yyyy-mm-dd&limit=30&page=4
{ "action": "order.lookup", "result": "success", "begin": "6/1/16", "end": "8/30/16", "page": 4, "limit": 30, "nextPage": 5, "total": 1048, "orders": [ { "order": "Qf1jNhlCSKGW5RJdfM7cTg", "id": "Qf1jNhlCSKGW5RJdfM7cTg", "reference": "FUR160824-6097-31167", "buyerReference": null, "ipAddress": "000.000.00.000", "completed": true, "changed": 1472061802969, "changedValue": 1472061802969, "changedInSeconds": 1472061802, "changedDisplay": "8/24/16", "language": "en", "live": false, "currency": "USD", "account": "cZnOkAUIQ2qCtcrTtyXgYQ", "payoutCurrency": "USD", "invoiceUrl": "https://yourexamplestore.onfastspring.com/account/order/YES160824-6097-31167/invoice", "total": 19.44, "totalDisplay": "$19.44", "totalInPayoutCurrency": 19.44, "totalInPayoutCurrencyDisplay": "$19.44", "tax": 1.44, "taxDisplay": "$1.44", "taxInPayoutCurrency": 1.44, "taxInPayoutCurrencyDisplay": "$1.44", "subtotal": 18, "subtotalDisplay": "$18.00", "subtotalInPayoutCurrency": 18, "subtotalInPayoutCurrencyDisplay": "$18.00", "discount": 2, "discountDisplay": "$2.00", "discountInPayoutCurrency": 2, "discountInPayoutCurrencyDisplay": "$2.00", "discountWithTax": 2.16, "discountWithTaxDisplay": "$2.16", "discountWithTaxInPayoutCurrency": 2.16, "discountWithTaxInPayoutCurrencyDisplay": "$2.16", "payment": { "type": "free", // payment method: "paypal", "amazon", "creditcard", "test", "bank", "alipay", "purchase-order", "free" "creditcard": "visa", // ONLY appears when "type" = "creditcard". Values = "visa", "mastercard", "amex", "discover", "jcb", "carteblanche", "dinersclub", "unionpay" "cardEnding": "4242", // ONLY appears when "type" = "creditcard". Last four digits of the card number "bank": "sofort" // ONLY appears when "type" = "bank". Values = "wire", "brazilwire", "ideal", "giropay", "sofort", "ecard", "sepa", "alipay" }, "customer": { "first": "Reenable", "last": "MailingList", "email": "ne1@all.com", "company": null, "phone": "1234567890" }, "address": { "city": "Santa Barbara", "regionCode": "CA", "regionDisplay": "California", "region": "California", "postalCode": "93101", "country": "US", "display": "Santa Barbara, California, 93101, US" }, "recipients": [ { "recipient": { "first": "Reenable", "last": "MailingList", "email": "ne1@all.com", "company": null, "phone": "1234567890", "account": "KJRTYQByS_WIcVQ-AZp6kw", "address": { "city": "Santa Barbara", "regionCode": "CA", "regionDisplay": "California", "region": "California", "postalCode": "93101", "country": "US", "display": "Santa Barbara, California, 93101, US" } } } ], "notes": [], "items": [ { "product": "physical", "quantity": 1, "display": "Physical", "sku": null, "subtotal": 9, "subtotalDisplay": "$9.00", "subtotalInPayoutCurrency": 9, "subtotalInPayoutCurrencyDisplay": "$9.00", "attributes": {"SystemExtension.eds": "true"}, "discount": 1, "discountDisplay": "$1.00", "discountInPayoutCurrency": 1, "discountInPayoutCurrencyDisplay": "$1.00", "coupon": "TEST", "fulfillments": {"physical_file_0": [ { "display": "malware.zip", "size": 4106, "file": "https://yourexamplestore.onfastspring.com/account/file/YES160824-6097-46172F", "type": "file" }]} }, { "product": "SystemExtension.eds", "quantity": 1, "display": "EDS", "sku": null, "subtotal": 9, "subtotalDisplay": "$9.00", "subtotalInPayoutCurrency": 9, "subtotalInPayoutCurrencyDisplay": "$9.00", "attributes": {"SystemExtension.eds": "true"}, "discount": 1, "discountDisplay": "$1.00", "discountInPayoutCurrency": 1, "discountInPayoutCurrencyDisplay": "$1.00", "coupon": "TEST", "fulfillments": {} } ], "coupons": ["TEST"] } ... ] }
// invalid begin or end date { "action": "order.lookup", "result": "error", "error": { "begin": "Invalid begin date" "end": "End date must be after begin date" } }
Get orders by product path AND date range
Example 4: Get orders by product path AND date range
GET /orders?products=product1&begin=yyyy-mm-dd&end=yyyy-mm-dd&limit=10&page=1
{ "action": "order.lookup", "result": "success", "begin": "6/1/16", "end": "7/30/16", "page": 1, "limit": 10, "nextPage": null, "total": 5, "orders": [ { "order": "sHwVlGLER9qJHKr6lkX5oA", "id": "sHwVlGLER9qJHKr6lkX5oA", "reference": "FUR160710-2490-94117", "buyerReference": null, "ipAddress": "000.000.00.000", "completed": true, "changed": 1468120080887, "changedValue": 1468120080887, "changedInSeconds": 1468120080, "changedDisplay": "7/10/16", "language": "en", "live": false, "currency": "USD", "account": "E93cH9zLS6ebdnrUjCYLFA", "payoutCurrency": "USD", "invoiceUrl": "https://yourexamplestore.onfastspring.com/account/order/YES160710-2490-94117/invoice", "total": 66.96, "totalDisplay": "$66.96", "totalInPayoutCurrency": 66.96, "totalInPayoutCurrencyDisplay": "$66.96", "tax": 4.96, "taxDisplay": "$4.96", "taxInPayoutCurrency": 4.96, "taxInPayoutCurrencyDisplay": "$4.96", "subtotal": 62, "subtotalDisplay": "$62.00", "subtotalInPayoutCurrency": 62, "subtotalInPayoutCurrencyDisplay": "$62.00", "discount": 0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "$0.00", "discountWithTax": 0, "discountWithTaxDisplay": "$0.00", "discountWithTaxInPayoutCurrency": 0, "discountWithTaxInPayoutCurrencyDisplay": "$0.00", "payment": { "type": "free", // payment method: "paypal", "amazon", "creditcard", "test", "bank", "alipay", "purchase-order", "free" "creditcard": "visa", // ONLY appears when "type" = "creditcard". Values = "visa", "mastercard", "amex", "discover", "jcb", "carteblanche", "dinersclub", "unionpay" "cardEnding": "4242", // ONLY appears when "type" = "creditcard". Last four digits of the card number "bank": "sofort" // ONLY appears when "type" = "bank". Values = "wire", "brazilwire", "ideal", "giropay", "sofort", "ecard", "sepa", "alipay" }, "customer": { "first": "test", "last": "order", "email": "ne1@all.com", "company": null, "phone": "1234567890" }, "address": { "addressLine1": "801 Garden Street", "city": "Santa Barbara", "regionCode": "CA", "regionDisplay": "California", "region": "California", "postalCode": "93101", "country": "US", "display": "Santa Barbara, California, 93101, US" }, "recipients": [ { "recipient": { "first": "New", "last": "Order", "email": "ne1@all.com", "company": null, "phone": "1234567890", "account": "KJRTYQByS_WIcVQ-AZp6kw", "address": { "addressLine1": "801 Garden Street", "city": "Santa Barbara", "regionCode": "CA", "regionDisplay": "California", "region": "California", "postalCode": "93101", "country": "US", "display": "Santa Barbara, California, 93101, US" } } } ], "notes": [], "items": [ { "product": "testbundle", "quantity": 3, "display": "TestBundle", "sku": null, "subtotal": 30, "subtotalDisplay": "$30.00", "subtotalInPayoutCurrency": 30, "subtotalInPayoutCurrencyDisplay": "$30.00", "attributes": {"SystemExtension.eds": "true"}, "discount": 0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "$0.00", "fulfillments": {} }, { "product": "physical", "quantity": 3, "display": "Physical", "sku": null, "subtotal": 0, "subtotalDisplay": "$0.00", "subtotalInPayoutCurrency": 0, "subtotalInPayoutCurrencyDisplay": "$0.00", "attributes": {"SystemExtension.eds": "true"}, "discount": 0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "$0.00", "fulfillments": {"physical_file_0": [ { "display": "malware.zip", "size": 4106, "file": "https://automation.test.qa.onfastspring.com/account/file/YES160710-2490-43134F", "type": "file" }]} }, { "product": "firstsub", "quantity": 3, "display": "firstSub", "sku": null, "subtotal": 0, "subtotalDisplay": "$0.00", "subtotalInPayoutCurrency": 0, "subtotalInPayoutCurrencyDisplay": "$0.00", "attributes": {"SystemExtension.eds": "true"}, "discount": 0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "$0.00", "subscription": "KNj-JrZyQ7i2yALyv5nv7Q", "fulfillments": { "firstsub_license_0": [ { "license": "1", "display": "License Key", "type": "license" }], "firstsub_file_0": [ { "display": "poty2006.zip", "size": 538835908, "file": "https://automation.test.qa.onfastspring.com/account/file/YES160710-2490-80119F", "type": "file" }] } }, { "product": "digitalphysical", "quantity": 1, "display": "digitalPhysical", "sku": null, "subtotal": 10, "subtotalDisplay": "$10.00", "subtotalInPayoutCurrency": 10, "subtotalInPayoutCurrencyDisplay": "$10.00", "attributes": {"SystemExtension.eds": "true"}, "discount": 0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "$0.00", "fulfillments": {"digitalphysical_file_0": [ { "display": "Anaconda2-2.4.1-MacOSX-x86_64.pkg", "size": 257787337, "file": "https://automation.test.qa.onfastspring.com/account/file/YES160710-2490-25147F", "type": "file" }]} }, { "product": "SystemExtension.shippingcalculation", "quantity": 1, "display": "Shipping", "sku": null, "subtotal": 12, "subtotalDisplay": "$12.00", "subtotalInPayoutCurrency": 12, "subtotalInPayoutCurrencyDisplay": "$12.00", "attributes": {"SystemExtension.eds": "true"}, "discount": 0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "$0.00", "fulfillments": {} }, { "product": "SystemExtension.eds", "quantity": 1, "display": "EDS", "sku": null, "subtotal": 10, "subtotalDisplay": "$10.00", "subtotalInPayoutCurrency": 10, "subtotalInPayoutCurrencyDisplay": "$10.00", "attributes": {"SystemExtension.eds": "true"}, "discount": 0, "discountDisplay": "$0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "$0.00", "fulfillments": {} } ] } ... ] }
Get Orders Using Only an End Date
Example 5: Get orders by specifying only the end date
Note: When no begin date is specified, the beginning date for the range defaults to 30 days.
GET /orders?end=yyyy-mm-dd
{ "action": "order.lookup", "result": "success", "end": "6/30/16", "page": 1, "limit": 50, "nextPage": null, "total": 9, "orders": [ { "order": "US5oKN5sRU2OUWxVwivl_Q", "id": "US5oKN5sRU2OUWxVwivl_Q", "reference": "FUR160629-3229-57108B", "buyerReference": null, "ipAddress": "000.000.00.000", "completed": true, "changed": 1467239032151, "changedValue": 1467239032151, "changedInSeconds": 1467239032, "changedDisplay": "6/29/16", "language": "en", "live": false, "currency": "USD", "account": "E93cH9zLS6ebdnrUjCYLFA", "payoutCurrency": "USD", "invoiceUrl": "https://yourexamplestore.onfastspring.com/account/order/YES160629-3229-57108B/invoice", "total": 10, "totalDisplay": "USD 10.00", "totalInPayoutCurrency": 10, "totalInPayoutCurrencyDisplay": "USD 10.00", "tax": 0, "taxDisplay": "USD 0.00", "taxInPayoutCurrency": 0, "taxInPayoutCurrencyDisplay": "USD 0.00", "subtotal": 10, "subtotalDisplay": "USD 10.00", "subtotalInPayoutCurrency": 10, "subtotalInPayoutCurrencyDisplay": "USD 10.00", "discount": 0, "discountDisplay": "USD 0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "USD 0.00", "discountWithTax": 0, "discountWithTaxDisplay": "USD 0.00", "discountWithTaxInPayoutCurrency": 0, "discountWithTaxInPayoutCurrencyDisplay": "USD 0.00", "payment": { "type": "free", // payment method: "paypal", "amazon", "creditcard", "test", "bank", "alipay", "purchase-order", "free" "creditcard": "visa", // ONLY appears when "type" = "creditcard". Values = "visa", "mastercard", "amex", "discover", "jcb", "carteblanche", "dinersclub", "unionpay" "cardEnding": "4242", // ONLY appears when "type" = "creditcard". Last four digits of the card number "bank": "sofort" // ONLY appears when "type" = "bank". Values = "wire", "brazilwire", "ideal", "giropay", "sofort", "ecard", "sepa", "alipay" }, "customer": { "first": "test", "last": "test", "email": "ne1@all.com", "company": null, "phone": "1234567890" }, "address": { "addressLine1": "272 Gonghang-ro", "city": "Jung-gu", "region": "Incheon", "postalCode": "40765", "country": "KR", "display": "272 Gonghang-ro, Jung-gu, Incheon, 40765, KR" }, "recipients": [ { "recipient": { "first": "test", "last": "test", "email": "ne1@all.com", "company": null, "phone": 1234567890, "account": "E93cH9zLS6ebdnrUjCYLFA", "address": { "addressLine1": "272 Gonghang-ro", "city": "Jung-gu", "region": "Incheon", "postalCode": "40765", "country": "KR", "display": "272 Gonghang-ro, Jung-gu, Incheon, 40765, KR" } } } ], "notes": [], "items": [ { "product": "firstsub", "quantity": 1, "display": "firstSub", "sku": null, "subtotal": 10, "subtotalDisplay": "USD 10.00", "subtotalInPayoutCurrency": 10, "subtotalInPayoutCurrencyDisplay": "USD 10.00", "discount": 0, "discountDisplay": "USD 0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "USD 0.00", "subscription": "1hrkNaKxRyizVyj_Lv9RCA" }] } ... ] }
Get Orders with Returns Only
Example 6: Get orders with returns only
GET /orders?begin=2018-07-16&end=2018-07-17&returns=true
{ "action": "order.lookup", "result": "success", "begin": "7/16/18", "end": "7/17/18", "page": 1, "limit": 50, "nextPage": null, "total": 1, "orders": [ { "order": "sLvABUuPTOmxuxxme6zyBA", "id": "sLvABUuPTOmxuxxme6zyBA", "reference": "FUR180716-1320-39108", "buyerReference": null, "ipAddress": "000.000.00.000", "completed": true, "changed": 1531768631874, "changedValue": 1531768631874, "changedInSeconds": 1531768631, "changedDisplay": "7/16/18", "language": "en", "live": false, "currency": "USD", "payoutCurrency": "USD", "invoiceUrl": "https://yourexamplestore.onfastspring.com/account/order/YES180716-1320-39108/invoice", "account": "5ta9yueaQ2mlc3UeSZi2Ew", "total": 59.99, "totalDisplay": "USD 59.99", "totalInPayoutCurrency": 59.99, "totalInPayoutCurrencyDisplay": "USD 59.99", "tax": 0, "taxDisplay": "USD 0.00", "taxInPayoutCurrency": 0, "taxInPayoutCurrencyDisplay": "USD 0.00", "subtotal": 59.99, "subtotalDisplay": "USD 59.99", "subtotalInPayoutCurrency": 59.99, "subtotalInPayoutCurrencyDisplay": "USD 59.99", "discount": 0, "discountDisplay": "USD 0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "USD 0.00", "discountWithTax": 0, "discountWithTaxDisplay": "USD 0.00", "discountWithTaxInPayoutCurrency": 0, "discountWithTaxInPayoutCurrencyDisplay": "USD 0.00", "billDescriptor": "FS* fsprg.com", "payment": { "type": "test", "cardEnding": "4242" }, "customer": { "first": "John", "last": "Doe", "email": "ne1@all.com", "company": null, "phone": null }, "address": { "addressLine1": "123 Elm St", "city": "Lisbon", "regionDisplay": "", "region": "", "postalCode": "93101", "country": "DE", "display": "123 Elm St, Lisbon, , 93101, DE" }, "recipients": [ { "recipient": { "first": "John", "last": "Doe", "email": "ne1@all.com", "company": null, "phone": null, "account": "5ta9yueaQ2mlc3UeSZi2Ew", "address": { "addressLine1": "123 Elm St", "city": "Lisbon", "regionDisplay": "", "region": "", "postalCode": "93101", "country": "DE", "display": "123 Elm St, Lisbon, , 93101, DE" } } } ], "notes": [], "items": [ { "product": "example-product-1", "quantity": 1, "display": "Example Product 1", "sku": "exprod1", "subtotal": 59.99, "subtotalDisplay": "USD 59.99", "subtotalInPayoutCurrency": 59.99, "subtotalInPayoutCurrencyDisplay": "USD 59.99", "discount": 0, "discountDisplay": "USD 0.00", "discountInPayoutCurrency": 0, "discountInPayoutCurrencyDisplay": "USD 0.00", "fulfillments": { "example-product-1_license_0": [ { "license": "Example-8QEl7sD8FKI56r4siL9c", "display": "License Key", "type": "license" } ], "example-product-1_file_2": [ { "display": "EXAMPLE.EXE", "size": 129, "file": "https://yourexamplestore.onfastspring.com/account/file/YES180716-1320-64112F", "type": "file" } ], "instructions": "Thank you for purchasing Example Product 1." } } ], "returns": [ { "return": "YxCkQcnTR_iX1iZJgQly8Q", "amount": 59.99, "amountDisplay": "USD 59.99", "amountInPayoutCurrency": 59.99, "amountInPayoutCurrencyDisplay": "USD 59.99" } ] } ] }
Update Order Tags and Attributes
POST /orders
Note
Subscription-related webhook events and API responses automatically pull order tags and product attributes from the original subscription order. Therefore, updating the tags or attributes of an order that created a subscription effectively updates the subscription as well.
{ "orders": [ { "order": "JL4ltRyBSTS0myETu7yJIA", // order ID to be updated "tags": { "TagKey1": "TagValue1", // order tag to be added or updated "TagKey2": "TagValue2" // order tag to be added or updated }, "items": [ { "product": "product-path", // product path of the product whose attributes will be added or updated "attributes": { "AttributeKey1": "AttributeValue1", // attribute to be added or updated "AttributeKey2": "AttributeValue2" // attribute to be added or updated } } ] } ] }
// Order ID not found { "orders": [ { "action": "order.update", "order": "[0]", "result": "error", "error": { "order": "Not found" } } ] } // Specified product path not found in specified order record { "orders": [ { "action": "order.update", "order": "JL4ltRyBSTS0myETu7yJIA", "result": "error", "error": { "items.example-product-2": "Product is not specified as a valid item in the order" } } ] }