Collapse Menu
Docs Home
Extensibility Options
Contact Support

/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

ParameterValuesDescription
begin yyyy-mm-ddfilters results to include transactions after the specified begin date (must be at least one day before the specified end date)
endyyyy-mm-ddfilters results to include transactions before the specified end date
limitintegerinteger limits the number of order records returned per page (default is 50 records)
pageintegerspecifies page number of results to be returned; used together with limit to control pagination
productsstringfilters results to include only transactions involving the specified product ID(s) / product path(s)
rebilltrue/falsefilters results to include only subscription rebill transactions or exclude all subscription rebill transactions
returnstrue/falsefilters results to include orders with or without returns; response includes returns array with return IDs where applicable
scopeall, live, testfilters results to include live transactions, test transactions, or both
statuscompleted, canceled, failedfilters 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

If you specify more than one order ID in the same GET request, the API response consists of an orders array (e.g. { orders: [ ) containing each order object. The example below illustrates the response when requesting a single order ID.
Response Example
{
    "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
            }
        }
    ]
}

Possible Error Response Example
{
  "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
   
Response Example
{
   "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
   
Response Example
{
   "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"]
      }
      ...
    ]
  }
Possible Error Response Example
// 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
   
Response Example
{
   "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
   
Response Example
{
   "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
   
Response Example
{
    "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

Updating order tags or product attributes replaces the current order tags or attributes; the update does not append additional tags or attributes.

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.
Request Example
{
  "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
          }
        }
      ]
    }
  ]
}
Possible Error Responses
// 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"
            }
        }
    ]
}

Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.