/orders

Last modified November 26, 2018

This article applies to Contextual Commerce. (Looking for Classic Commerce documentation?)

Orders

Use this endpoint to retrieve information about a single order or create new orders on behalf of the customer.

Orders can be retrieved by order ID, product path, or date range. You can optionally combine parameters in your request, for example retrieving all orders for a certain product that occurred in a given date range.

When retrieving multiple orders, the response will be paginated 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.

Orders can only be created if payment information is available for a customer and this functionality was enabled by FastSpring for your vendor account. For more information see Creating new orders for customers with payment information on file.

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 prior to specified end date)
end yyyy-mm-dd filters results to include transactions before the specified end date
limit 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

Get orders by ID

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 response will include an orders array (e.g. { orders: [ ) at the top level, consisting of each individual order object. The example below illustrates the response when requesting a single order ID.
Response example
{
    "order": "WS6Y8Jt_RtGxIiGimQqBWg",                                // internal order ID
    "id": "WS6Y8Jt_RtGxIiGimQqBWg",                                   // backward compatibility
    "reference": "FUR180129-1746-44115",                              // customer-facing order reference
    "buyerReference": null,                                           // optional purchase order number entered by the customer 
    "completed": true,                                                // false if order failed, was declined, or is pending
    "changed": 1517251461223,                                         // date of the most recent update to this order record, in milliseconds
    "changedValue": 1517251461223,                                    // date of the most recent update to this order record, in milliseconds (backward compatibility)
    "changedInSeconds": 1517251461,                                   // date of the most recent update to this order record, in seconds
    "changedDisplay": "1/29/18",                                      // 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://furiousfalcon.onfastspring.com/account/order/FUR180129-1746-44115/invoice",
    "account": "N8FjcSWcQNeYCc-suM1O8g",                              // FastSpring-generated customer account ID
    "total": 0,
    "totalDisplay": "$0.00",
    "totalInPayoutCurrency": 0,
    "totalInPayoutCurrencyDisplay": "$0.00",
    "tax": 0,
    "taxDisplay": "$0.00",
    "taxInPayoutCurrency": 0,
    "taxInPayoutCurrencyDisplay": "$0.00",
    "subtotal": 0,
    "subtotalDisplay": "$0.00",
    "subtotalInPayoutCurrency": 0,
    "subtotalInPayoutCurrencyDisplay": "$0.00",
    "discount": 0,
    "discountDisplay": "$0.00",
    "discountInPayoutCurrency": 0,
    "discountInPayoutCurrencyDisplay": "$0.00",
    "discountWithTax": 0,
    "discountWithTaxDisplay": "$0.00",
    "discountWithTaxInPayoutCurrency": 0,
    "discountWithTaxInPayoutCurrencyDisplay": "$0.00",
    "billDescriptor": "FS* fsprg.com",
    "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": "Marcellus",
        "last": "Walrus",
        "email": "ne1@all.com",
        "company": "Walrus Exports, LLC",
        "phone": null
    },
    "address": {
        "addressLine1": "801 Garden St.",                             // for physical product purchase or when Storefront is configured to force collection
        "city": "Santa Barbara",                                      // for physical product purchase or when Storefront is configured to force collection
        "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": "Marcellus",
                "last": "Walrus",
                "email": "ne1@all.com",
                "company": "Walrus Exports, LLC",
                "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": "multi-subscription-pack",
            "quantity": 1,
            "display": "Multi-Subscripition Pack",
            "sku": null,
            "subtotal": 0,
            "subtotalDisplay": "$0.00",
            "subtotalInPayoutCurrency": 0,
            "subtotalInPayoutCurrencyDisplay": "$0.00",
		    "attributes": {
                 "ProductAttributeKey1": "ProductAttributeValue1",    // key and value are defined under Products > More > Custom Attributes (Advanced)
                 "ProductAttributeKey2": "ProductAttributeValue2",    // key and value are defined under Products > More > Custom Attributes (Advanced)
                 "ProductAttributeKey3": "ProductAttributeValue3"     // key and value are defined under Products > More > Custom Attributes (Advanced)
            },
            "discount": 0,
            "discountDisplay": "$0.00",
            "discountInPayoutCurrency": 0,
            "discountInPayoutCurrencyDisplay": "$0.00",
			"coupon": "FREE",                                         // coupon code (not coupon path / ID) applied to the current order item (if applicable)                               
            "subscription": "AvXuBV4TQJWbC_2rlm1ZwQ",                 // FastSpring-generated subscription ID for the subscriptino associated with the current item
            "fulfillments": {}
        },
        {
            "product": "eggs-basic",
            "quantity": 1,
            "display": "Eggs Basic",
            "sku": "furious11",
            "subtotal": 0,
            "subtotalDisplay": "$0.00",
            "subtotalInPayoutCurrency": 0,
            "subtotalInPayoutCurrencyDisplay": "$0.00",
            "discount": 0,
            "discountDisplay": "$0.00",
            "discountInPayoutCurrency": 0,
            "discountInPayoutCurrencyDisplay": "$0.00",
			"coupon": "FREE",                                         // coupon code (not coupon path / ID) applied to the current order item (if applicable)
            "fulfillments": {
                "eggs-basic_license_1": [
                    {
                        "license": "GVJHacO2enKIA4xc8FqX",
                        "display": "License Key",
                        "type": "license"
                    }
                ],
                "instructions": "<p>Thank you for purchasing <strong><em>Eggs, Basic Edition</em></strong>. Your license key is as follows:</p><p><br/> License Key: GVJHacO2enKIA4xc8FqX<br/></p><p>To register the product, select <strong>Help</strong> | <strong>About Eggs</strong> and then click <strong>Register Now</strong> and copy and paste in the license key above. Click <strong>Activate</strong> to finish registering the product and remove trial version limitations.</p>"
            },
            "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" or "addon"
                "path": "multi-subscription-pack"                    // product path / ID of the parent item
            }
        },
        {
            "product": "nest-1",
            "quantity": 1,
            "display": "Nest Basic",
            "sku": "falcon9",
            "subtotal": 0,
            "subtotalDisplay": "$0.00",
            "subtotalInPayoutCurrency": 0,
            "subtotalInPayoutCurrencyDisplay": "$0.00",
            "discount": 0,
            "discountDisplay": "$0.00",
            "discountInPayoutCurrency": 0,
            "discountInPayoutCurrencyDisplay": "$0.00",
			"coupon": "FREE",                                         // coupon code (not coupon path / ID) applied to the current order item (if applicable)
            "fulfillments": {
                "nest-1_license_0": [
                    {
                        "license": "pZSjhMCKLneuT32sQN2G",
                        "display": "License Key",
                        "type": "license"
                    }
                ],
                "nest-1_file_1": [
                    {
                        "display": "Nest.exe",
                        "size": 5769,
                        "file": "https://furiousfalcon.onfastspring.com/account/file/FUR180129-1746-77119F",
                        "type": "file"
                    }
                ],
                "instructions": "<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>"
            },
            "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" or "addon"
                "path": "multi-subscription-pack"                    // product path / ID of the parent item
            }
        },
        {
            "product": "facon-basic",
            "quantity": 1,
            "display": "Falcon Basic",
            "sku": null,
            "subtotal": 0,
            "subtotalDisplay": "$0.00",
            "subtotalInPayoutCurrency": 0,
            "subtotalInPayoutCurrencyDisplay": "$0.00",
            "discount": 0,
            "discountDisplay": "$0.00",
            "discountInPayoutCurrency": 0,
            "discountInPayoutCurrencyDisplay": "$0.00",
			"coupon": "FREE",                                         // coupon code (not coupon path / ID) applied to the current order item (if applicable)
            "fulfillments": {
                "facon-basic_license_0": [
                    {
                        "license": "dmfFvUwbI1DU5nnkhswW",
                        "display": "License Key",
                        "type": "license"
                    }
                ]
            },
            "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" or "addon"
                "path": "multi-subscription-pack"                    // product path / ID of the parent item
            }
        }
    ]
	"coupons": [
      "FREE"                                                          // coupon code (not coupon path / ID) applied to the order (if applicable)
	],
    "action": "order.get",
    "result": "success"
}



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,
         "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://furiousfalcon.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",
         "completed": true,
         "changed": 1472061802969,
         "changedValue": 1472061802969,
         "changedInSeconds": 1472061802,
         "changedDisplay": "8/24/16",
         "language": "en",
         "live": false,
         "currency": "USD",
         "account": "cZnOkAUIQ2qCtcrTtyXgYQ",
         "payoutCurrency": "USD",
         "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/FUR160824-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://furiousfalcon.onfastspring.com/account/file/FUR160824-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?product=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",
         "completed": true,
         "changed": 1468120080887,
         "changedValue": 1468120080887,
         "changedInSeconds": 1468120080,
         "changedDisplay": "7/10/16",
         "language": "en",
         "live": false,
         "currency": "USD",
         "account": "E93cH9zLS6ebdnrUjCYLFA",
         "payoutCurrency": "USD",
         "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/FUR160710-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/FUR160710-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/FUR160710-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/FUR160710-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

// 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",
         "completed": true,
         "changed": 1467239032151,
         "changedValue": 1467239032151,
         "changedInSeconds": 1467239032,
         "changedDisplay": "6/29/16",
         "language": "en",
         "live": false,
         "currency": "USD",
         "account": "E93cH9zLS6ebdnrUjCYLFA",
         "payoutCurrency": "USD",
         "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/FUR160629-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,
            "completed": true,
            "changed": 1531768631874,
            "changedValue": 1531768631874,
            "changedInSeconds": 1531768631,
            "changedDisplay": "7/16/18",
            "language": "en",
            "live": false,
            "currency": "USD",
            "payoutCurrency": "USD",
            "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/FUR180716-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": "falcon",
                    "quantity": 1,
                    "display": "Furious Falcon",
                    "sku": "falcon6abc123",
                    "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": {
                        "falcon_license_0": [
                            {
                                "license": "Falcon-8QEl7sD8FKI56r4siL9c",
                                "display": "License Key",
                                "type": "license"
                            }
                        ],
                        "falcon_file_2": [
                            {
                                "display": "FALCON4.EXE",
                                "size": 129,
                                "file": "https://furiousfalcon.onfastspring.com/account/file/FUR180716-1320-64112F",
                                "type": "file"
                            }
                        ],
                        "instructions": "<p>Thank you for purchasing <em>Falcon</em>. To register, please launch the trial version and select <strong>Help</strong> | <strong>Register Falcon</strong>. Then, copy and paste the license key above into the <strong>License Key</strong> field and click <strong>Submit</strong>.</p>"
                    }
                }
            ],
            "returns": [
                {
                    "return": "YxCkQcnTR_iX1iZJgQly8Q",
                    "amount": 59.99,
                    "amountDisplay": "USD 59.99",
                    "amountInPayoutCurrency": 59.99,
                    "amountInPayoutCurrencyDisplay": "USD 59.99"
                }
            ]
        }
    ]
}



Create New Order and Complete the Charge

POST /orders

Note about creating new transactions via the API

As the merchant and seller of record for all transactions we process,  only  FastSpring can collect customers' payment details (e.g. credit card numbers). Thus, in order to  create new transactions  via the FastSpring API, the customer must already have a payment method on file with FastSpring. Read more about creating orders for customers with payment methods on file here.
Request Example
{ 
   "account":"uKj7izONRfanVwX193eG_A",              // must have billing method on file
   "coupon":"",                                     // optional couponID
   "tags":{ 
      "tag1":"value1"
   },
   "currency":"USD",
   "items":[ 
      { 
         "product":"falcon-monthly-subscriptions",  // productID
         "quantity":1,
         "pricing":{ 
            "trial":0,                              // days
            "renew":"auto",                         // or "manual", "opt-auto", "opt-manual"
            "interval":"month",                     // or "adhoc", "day", "week", "year"
            "intervalLength":1,                     // required if "intervral" is specified and is not "adhoc"
            "quantityBehavior":"allow",             // or "lock" or "hide"
            "quantityDefault":1,
            "price":{ 
               "USD":14.95,                         // currency must be enabled in the Store Settings
               "EUR":10.99
            }
         },
         "attributes":{ 
            "ATTRIBUTE1":"value1"                   // optional custom product-level attributes
         }
      }
   ]
}
Response Example
{
  "order": "U8OsgSHiTkWhKWvq0D1k9w",                                    // internal order ID
  "id": "U8OsgSHiTkWhKWvq0D1k9w",                                       // backward compatibility
  "reference": "FUR160822-8238-54122",                                  // customer-facing order reference
  "completed": true,                                                    // false if order failed, was declined, or is pending
  "changed": 1471894849295,                                             // date of the most recent update to this order record, in milliseconds
  "changedValue": 1471894849295,
  "changedInSeconds": 1471894849,                                       // date of the most recent update to this order record, in seconds
  "changedDisplay": "8/22/16",                                          // 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-digit 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",
  "account": "uKj7izONRfanVwBL9eiG_A",                                  // FastSpring-generated customer account ID
  "payoutCurrency": "USD",
  "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/FUR160822-8238-54122/invoice",
  "total": 14.95,
  "totalDisplay": "$14.95",
  "totalInPayoutCurrency": 14.95,
  "totalInPayoutCurrencyDisplay": "$14.95",
  "tax": 0,
  "taxDisplay": "$0.00",
  "taxInPayoutCurrency": 0,
  "taxInPayoutCurrencyDisplay": "$0.00",
  "subtotal": 14.95,
  "subtotalDisplay": "$14.95",
  "subtotalInPayoutCurrency": 14.95,
  "subtotalInPayoutCurrencyDisplay": "$14.95",
  "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": "John",
    "last": "Doe",
    "email": "ne1@all.com",
    "company": null,
    "phone": null
  },
  "address": {
    "country": "US",
    "display": "US"
  },
  "recipients": [
      {
          "recipient": {
              "first": "John",
              "last": "Doe",
              "email": "ne1@all.com",
              "company": null,
              "phone": null,
              "account": "uKj7izONRfanVwBL9eiG_A",
              "address": {
                  "country": "US",
                  "display": "US"
              }
          }
      }
  ],
  "tags": {
    "tag1": "value1"                                                   // as specified in POST /orders
  },
  "notes": [],
  "items": [
    {
      "product": "falcon-monthly-subscriptions",
      "quantity": 1,
      "display": "Falcon Monthly Subscription",
      "sku": "furious10",
      "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)
      },
      "discount": 0,
      "discountDisplay": "$0.00",
      "discountInPayoutCurrency": 0,
      "discountInPayoutCurrencyDisplay": "$0.00",
      "subscription": "j4v1k7ymTjWP_ZX2rP4M-A"                         // subscription ID
    }
  ]
}


Update Order Tags and Attributes

POST /orders
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.eggs": "Product is not specified as a valid item in the order"
            }
        }
    ]
}