This article provides information about the /returns endpoint of the FastSpring API. For more information about the API itself, please see About the FastSpring API.

Using this endpoint, you can retrieve return details or create full order returns. For more information about returns, please see Refunding Orders.

 

Get One or More Returns

GET /returns/{id1}[,{id2},{id3},...]

   

Get returns by id response
{
	"returns": [
	{
		"return": "QpMoe70PT5mMb5OMT4N5lA",                             // return ID
		"reference": "SUD160811-6921-74128X",                           // customer-facing return refernce (not the original order reference)
		"completed": true,                                              // false if return is pending
		"changed": 1470953997043,                                       // date of the last update to this return record, in milliseconds
		"changedValue": 1470953997043,
		"changedInSeconds": 1470953997,                                 // date of the last update to this return record, in seconds
		"changedDisplay": "8/11/16",                                    // date of the last update to this return record, formatted for display based on the language in which the order was processed, as selected by the customer
		"live": false,                                                  // true if not a test order
		"account": "_sOMzG2pSIyAeWXkcoNgUA",                            // FastSpring-generated customer account ID
		"currency": "USD",
		"payoutCurrency": "USD",
		"totalReturn": 10.0,
		"totalReturnDisplay": "$10.00",
		"totalReturnInPayoutCurrency": 10.0,
		"totalReturnInPayoutCurrencyDisplay": "$10.00",
		"tax": 0.0,
		"taxDisplay": "$0.00",
		"taxInPayoutCurrency": 0.0,
		"taxInPayoutCurrencyDisplay": "$0.00",
		"subtotal": 10.0,
		"subtotalDisplay": "$10.00",
		"subtotalInPayoutCurrency": 10.0,
		"subtotalInPayoutCurrencyDisplay": "$10.00",
		"totalRefundInPayoutCurrency": 10.0,
		"payment": {
			"type": "test",
			"cardEnding": "4242"
		},
		"reason": "Product Not Received",                                // return reason selected by publisher / seller when processing the refund
		"note": "Note during the refund of the order(Canceling The Subscription)",     // optional return comment entered by publisher / seller when processing the refund
                "type": "RETURN",                                                // return type: CHARGEBACK, PAYMENTRISK, PAYPAL, RETURN
		"original": {
			"id": "embMdXyCQZinGxkk2v85GA", 
			"order": "embMdXyCQZinGxkk2v85GA",                           // internal ID of the original order
			"reference": "SUD160811-1752-43151",                         // customer-facing reference for the original order
			"account": "_sOMzG2pSIyAeWXkcoNgUA",                         // FastSpring-generated customer account ID of the original order
			"currency": "USD",
			"payoutCurrency": "USD",
			"total": 10.0,
			"totalDisplay": "$10.00",
			"totalInPayoutCurrency": 10.0,
			"totalInPayoutCurrencyDisplay": "$10.00",
			"tax": 0.0,
			"taxDisplay": "$0.00",
			"taxInPayoutCurrency": 0.0,
			"taxInPayoutCurrencyDisplay": "$0.00",
			"subtotal": 10.0,
			"subtotalDisplay": "$10.00",
			"subtotalInPayoutCurrency": 10.0,
			"subtotalInPayoutCurrencyDisplay": "$10.00",
			"notes": [
			    {
				"note": "Before canceling the subscription",             // example note entered by the publisher / seller on the original order record (not the refund)
				"creator": "admin@yourexamplestore.com"                     // user ID of the seller's agent who entered the note
			    }
			],
			"subscriptions": 
			[
			"RPN1Bp62Q3mEXloZvxUxmg"                                     // ID of the subscription associated with the returned order (if any)
			]
		},
		"customer": {
			"first": "Test",
			"last": "Order",
			"email": "test@tes.com",
			"company": "Test",
			"phone": "1234567890"
		},
		"items": [
		    {
			"product": "newtestsuborder",
			"quantity": 1,
			"display": "newtestsuborder",
			"sku": null,
			"subtotal": 10.0,
			"subtotalDisplay": "$10.00",
			"subtotalInPayoutCurrency": 10.0,
			"subtotalInPayoutCurrencyDisplay": "$10.00",
			"subscription": "RPN1Bp62Q3mEXloZvxUxmg"                     // ID of the subscription associated with the returned order (if any)
		     }
		],
		"action": "return.get",
		"result": "success"
	}
  ]
}

 

POST one or more full order returns

POST /returns

 Note

At this time, it is not possible to perform partial refunds or return specific line items via the API. However, you can still do this via the FastSpring App. For help with these types of returns, please see Refunding Orders.

 Note

Processing a full return via the API for an order associated with a subscription does not automatically cancel the subscription. You can cancel the subscription by calling DELETE /subscriptions/{subscriptionId}.
Sample Request
{ 
  "returns":[ 
    { 
      "order":"17VblT1XR1aAnIIScCgpfw",                     // order ID OR order reference to be returned
      "reason":"DUPLICATE_ORDER",                           // PRODUCT_NOT_RECEIVED | PRODUCT_DIFFERENCE | FRAUD | ORDER_ERROR | DISCOUNT | DUPLICATE_ORDER | COMPATIBILITY_ISSUE | OTHER (NONE if missing)
      "note":"As requested by customer",                    // optional, customer-visible note explaining the return reason
      "notification":"ORIGINAL"                             // notify the customer of the return via email? "ORIGINAL" = yes; "NONE" = no
    }
  ]
}
Sample Response
{
    "returns": [
        {
            "return": "JV8jCQrJT1GD7yndYgrorw",
            "reference": "FUR191003-4739-52106X",
            "completed": true,
            "changed": 1570130905372,
            "changedValue": 1570130905372,
            "changedInSeconds": 1570130905,
            "changedDisplay": "10/3/19",
            "live": true,
            "account": "2-hl9JWwQrualioCsY5lbg",
            "currency": "USD",
            "payoutCurrency": "USD",
            "totalReturn": 5.31,
            "totalReturnDisplay": "$5.31",
            "totalReturnInPayoutCurrency": 5.31,
            "totalReturnInPayoutCurrencyDisplay": "$5.31",
            "tax": 0.36,
            "taxDisplay": "$0.36",
            "taxInPayoutCurrency": 0.36,
            "taxInPayoutCurrencyDisplay": "$0.36",
            "subtotal": 4.95,
            "subtotalDisplay": "$4.95",
            "subtotalInPayoutCurrency": 4.95,
            "subtotalInPayoutCurrencyDisplay": "$4.95",
            "totalRefundInPayoutCurrency": 5.31,
            "payment": {
                "type": "creditcard",
                "creditcard": "visa",
                "cardEnding": "0369"
            },
            "reason": "DUPLICATE_ORDER",
            "note": "As requested by customer",
            "original": {
                "id": "kfPW5xbyTG-TuivKhtZYrA",
                "order": "kfPW5xbyTG-TuivKhtZYrA",
                "reference": "FUR191003-8210-23117",
                "account": "2-hl9JWwQrualioCsY5lbg",
                "currency": "USD",
                "payoutCurrency": "USD",
                "total": 5.31,
                "totalDisplay": "$5.31",
                "totalInPayoutCurrency": 5.31,
                "totalInPayoutCurrencyDisplay": "$5.31",
                "tax": 0.36,
                "taxDisplay": "$0.36",
                "taxInPayoutCurrency": 0.36,
                "taxInPayoutCurrencyDisplay": "$0.36",
                "subtotal": 4.95,
                "subtotalDisplay": "$4.95",
                "subtotalInPayoutCurrency": 4.95,
                "subtotalInPayoutCurrencyDisplay": "$4.95",
                "notes": []
            },
            "customer": {
                "first": "Leeroy",
                "last": "Jenkins",
                "email": "ne1@all.com",
                "company": null,
                "phone": null
            },
            "items": [
                {
                    "product": "eggs",
                    "quantity": 1,
                    "display": "Eggs",
                    "sku": "falcon1",
                    "subtotal": 4.95,
                    "subtotalDisplay": "$4.95",
                    "subtotalInPayoutCurrency": 4.95,
                    "subtotalInPayoutCurrencyDisplay": "$4.95",
                    "attributes": {
                        "conditions": "{exclude:{countries:['AT','GB']}}"
                    }
                }
            ],
            "action": "return.create",
            "result": "success"
        }
    ]
}

Using query parameters, the GET /quotes {id} endpoint can retrieve a single quote by it’s ID or list a collection of existing quotes that meet the custom search criteria.

Request bodies are not provided for a Retrieve Quotes request. If a request body is provided, it will be ignored.

Example Response

Fail to Retrieve Quote by ID

The request below failed to retrieve a quote by ID.

Get Open all Quotes

The example below retrieves all quotes with a status of OPEN .

Get Quotes within a Specified Date Range

The example request below retrieves the 25 most recently created quotes within a specified date range. 

 

Retrieve Quote Responses

Successful Responses

Error Responses

The POST /quotes/{id}/cancel endpoint cancels a quote, and sets the status to CANCELED. After this, the quoteURL no longer displays the quote.

Request Bodies are not required for a DeleteQuote request. If a request body is provided, it will be ignored.

Example Response

The PUT /quotes/{id} endpoint updates an existing quote with the attributes you provide in the request. You must include all attributes in the request, otherwise they will either be cleared or reset to default values.

You can only update a quote with the Open status.

Required Attributes

Attribute Type Description Constraint
coupon string A coupon code for the quote. (This is not a coupon ID) If a coupon is present, items will be updated as necessary. 

If the coupon is blank, null, or missing from the request, any previous coupon will be removed. 

currency string The three-letter ISO code of the currency of the quote If the currency is updated, items will be updated as necessary. 
expirationDateDays number Number of days after quote creation that it expires This will update the expires and expiresDisplay attributes. 
fulfillmentTerm string The fulfillment term for the quote  
items string The items included in the quote  
name string A descriptive name for the quote  
notes string Prospect-facing notes that will appear on the quote  
netTermDays integer The net terms days for the quote. 
When value is 0, payment is required immediately, prior to order acceptance.
Must be one of: 0, 1, 7, 14, 30, 45, 60, 90
recipient contact The quote recipient’s contact information, including: email address, first name, last name  
recipientAddress address The recipient’s address information, including: city, country, postal code, and region If the country attribute of recipientAddress is updated, items will be updated as necessary. 

If the postalCode attribute of recipientAddress is updated items will be updated as necessary.

tags object Key-value pairs for your internal tracking. Tags are invisible to your prospect. FastSpring does not utilize your tags  
taxId string A tax ID for the quote If a taxId is present, items will be updated as necessary. 

If the taxId is blank, null, or missing from the request, any previous taxId will be removed and items will be updated as necessary. 

UpdateQuote Responses

Successful Responses:

Error Responses:

Example: Update the Name

The example below updates quote with the ID number QU123XYZABC456DEF789GHI0123Q to fix a typo in the recipient’s last name.

Use the /quotes API endpoint to efficiently process and manage your B2B orders and billing capabilities, including quote creation, digital invoicing, and order management. With this endpoint, you can:

Unlike other FastSpring APIs, this API utilizes a POST request for creating resources, and a PUT request for updating resources.

Endpoints

For additional information regarding each endpoint, click on the link to access the corresponding documentation.

For information regarding the Address, Contact, and Items attributes, see /quotes – Additional Attributes.

Quote Response Contents

Attribute Type Description
id string A unique identifier for the quote
buyerGenerated boolean Flag to determine if the quote was generated by a prospect
coupon string A coupon code for the quote. (This is not a coupon ID)
created string Date the quote was created in the format: 
YYYY-MM-DD’T’HH:MM:SS
createdBy contact Contact information of the quote creator, including their first name, last name, and email
currency string The three-letter ISO code of the currency of the quote
discount number The total discount amount for the quote. This is the sum of all discounts on the quote
discountDisplay string The formatted display for the discount
discountInPayoutCurrency number The discount in the currency of the FastSpring payout
discountInPayoutCurrencyDisplay string The formatted display for the discountInPayoutCurrency
expirationDateDays number Number of days after quote creation that it expires
expires string The expiration date of the quote
YYYY-MM-DD’T’HH:MM:SS
fulfillmentTerm string The fulfillment term for the quote
items item[] The items included in the quote
name string A descriptive name for the quote
notes string Prospect-facing notes that will appear on the quote
netTermDays number The number of days an invoice is due by default. If 0, immediate payment is required before the order is accepted.
quoteURL string The URL of the quote. This is the URL that you send to the prospect.
recipient contact The quote recipient’s contact information, including: email address, first name, last name
recipientAddress address The recipient’s address information, including: city, country, postal code, and region
status string The status of the quote:
OPEN – the quote has been created
PENDING PAYMENT – the quote has been accepted, but not paid
COMPLETED – the prospect has paid the quote
CANCELED – the quote has been canceled
EXPIRED – the expiration date has passed with no payment
statusHistory statusHistory The status history of the quote
tags object Key-value pairs for your internal tracking. Tags are invisible to your prospect. FastSpring does not utilize your tags
tax number The total tax for the quote
taxDisplay string The formatted display for tax
taxId string A tax ID for the quote
taxInPayoutCurrency number The tax in the FastSpring payout currency
taxInPayoutCurrencyDisplay string The formatted display for taxInPayoutCurrency
total number The total for the quote
totalInPayoutCurrency number The total in the FastSpring payout currency
totalInPayoutCurrencyDisplay string the formatted display for the totalInPayoutCurrency 
updated number The date the quote was last updated. Format: YYYY-MM-DD’T’HH:MM:SS

Quote Response Example

 

Attribute DefaultValue

Most attributes in the /quotes API have a default value assigned from the preexisting settings, products, and coupons in your FastSpring Store.

The DefaultValue is used in POST request bodies (such as creating a quote), and PUT request bodies (such as updating a quote). Attributes with a store-defined default value will be marked in the Note section for the request attributes.

For example, In the CreateQuoteRequest object, the notes, expirationDateDays, and netTermDays attributes have default values set within your store-level settings.

All attributes that have a DefaultValue associated to them are always Optional Request Attributes and should be left out of the request body if you wish to use the default value. To override an attribute’s DefaultValue, include the optional attribute in the request with a valid value.

Example: Default Notes Value

This example demonstrates using the DefaultValue configured in your store for the notes attribute in a CreateQuote request.

// "notes" attribute is missing

 

// "notes" attribute set to null 

Example: Override the Default Value

The example below demonstrates overriding the DefaultValue configured in your store for the notes attribute in a CreateQuote request.

Example: Override the Default Value to an Empty String

The example below demonstrates overriding your Store’s DefaultValue for the notes attribute to an empty string.

Table of Contents

Webhook Events

Typically, server webhook events are sent via HTTP posts, but you can also use API calls to retrieve previous webhook events. By making a GET request to the /events endpoint of the FastSpring API, you can retrieve the payloads of previous webhook events.

Events are either processed or unprocessed, depending on whether your webhook endpoint has acknowledged the handling of the event. You can also make a POST request to the /events endpoint to mark a specific event as processed. To learn more about acknowledging events, please see About Webhooks.

The webhooks system generates the event contents at the time of each transaction, subscription, or other activity. If you do not subscribe to webhook events, FastSpring does not generate the events. Therefore, you cannot use the /events endpoint to retrieve details of any activity that occurred before you subscribed to the event.

For example, suppose the following are true:

In this example, you would be able to retrieve Wednesday's order via /events. However, even after you subscribe to order.completed, a call to /events would not return an order.completed event for Monday's transaction. At the time of the transaction, there was no subscription to order.completed, and so no event was generated.

You could, however, retrieve the details of Monday's order via the /orders endpoint – which does not rely on webhook event generation.

Certain modifiers are required when making a GET request to the /events endpoint of the API. Requests must include either the begin modifier to specify the Unix date of the first event to be returned, or else the days modifier to specify the number of previous days' worth of events to be returned. In either case, the API does not return items more than 30 days old. Therefore, if you specify a begin date, it must be no more than 30 days past. Likewise, the number of days specified using the days parameter must not be greater than 30.

 Note

Currently, only events posted to the topmost webhook configuration in your FastSpring App (as shown under Integrations → Webhooks) can be accessed or updated via the /events endpoint of the API. 

 

Modifiers

Limited to 25 results returned. The results contain a "more" attribute if there are more results beyond 25. To page to additional results, the timestamp of the nearest event should be fed into begin/end (narrowing the timeframe).

 

Get Multiple Events

Get processed or acknowledged events:

GET /events/processed?days=5

Get unprocessed events:

GET /events/unprocessed?begin=1542153600000

The response structure is nearly identical to the structure of Webhooks, except the response also includes some additional data:

Example Response
{
    "action": "events.get",
    "result": "success",
    "page": null,
    "limit": null,
    "nextPage": null,
    "total": 0,
    "events": [
        {
            "id": "88qMx0P2RZCalzQ5ERXfXA",
            "processed": false,
            "created": 1542239788941,
            "type": "payoutEntry.created",
            "live": false,
            "data": {
                "orderId": "EGr98BxdQ-idUfSZf_g-gw",
                "reference": "YES200314-8442-49161",
                "live": false,
                "order": {
                    "order": "EGr98BxdQ-idUfSZf_g-gw",
                    "id": "EGr98BxdQ-idUfSZf_g-gw",
                    "reference": "YES200314-8442-49161",
                    "buyerReference": null,
                    "completed": true,
                    "changed": 1542239788922,
                    "changedValue": 1542239788922,
                    "changedInSeconds": 1542239788,
                    "changedDisplay": "03/14/20",
                    "language": "en",
                    "live": false,
                    "currency": "USD",
                    "payoutCurrency": "USD",
                    "invoiceUrl": "https://youexamplestore.onfastspring.com/account/order/FUR181114-8442-49161/invoice",
                    "account": "N8FjcSWcQNeYCc-suM1O8g",
                    "total": 59.99,
                    "totalDisplay": "$59.99",
                    "totalInPayoutCurrency": 59.99,
                    "totalInPayoutCurrencyDisplay": "$59.99",
                    "tax": 0,
                    "taxDisplay": "$0.00",
                    "taxInPayoutCurrency": 0,
                    "taxInPayoutCurrencyDisplay": "$0.00",
                    "subtotal": 59.99,
                    "subtotalDisplay": "$59.99",
                    "subtotalInPayoutCurrency": 59.99,
                    "subtotalInPayoutCurrencyDisplay": "$59.99",
                    "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",
                        "cardEnding": "4242"
                    },
                    "customer": {
                        "first": "Marcellus",
                        "last": "Walrus",
                        "email": "ne1@all.com",
                        "company": "Acme, Inc.",
                        "phone": null
                    },
                    "address": {
                        "city": "Santa Barbara",
                        "regionCode": "CA",
                        "regionDisplay": "California",
                        "region": "California",
                        "postalCode": "93101",
                        "country": "US",
                        "display": "Santa Barbara, California, 93101, US"
                    },
                    "recipients": [
                        {
                            "recipient": {
                                "first": "Marcellus",
                                "last": "Walrus",
                                "email": "ne1@all.com",
                                "company": "Acme, Inc.,
                                "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-product-1",
                            "quantity": 1,
                            "display": "Example Product 1",
                            "sku": "skuex1",
                            "subtotal": 59.99,
                            "subtotalDisplay": "$59.99",
                            "subtotalInPayoutCurrency": 59.99,
                            "subtotalInPayoutCurrencyDisplay": "$59.99",
                            "discount": 0,
                            "discountDisplay": "$0.00",
                            "discountInPayoutCurrency": 0,
                            "discountInPayoutCurrencyDisplay": "$0.00",
                            "fulfillments": {
                                "example-product-1_file_2": [
                                    {
                                        "display": "EXAMPLE.EXE",
                                        "size": 129,
                                        "file": "https://yourexamplestore.onfastspring.com/account/file/YES200314-8442-79162F",
                                        "type": "file"
                                    }
                                ],
                                "example-product-1_license_0": [
                                    {
                                        "license": "Example-aw0r5H3YKBf8w9FNSqI2",
                                        "display": "License Key",
                                        "type": "license"
                                    }
                                ],
                                "instructions": "Thank you for purchasing Example Product 1. To register, please launch the trial version and select Help | Register Example Product 1. Then, copy and paste the license key above into the License Key field and click Submit."
                            }
                        }
                    ]
                },
                "account": {
                    "id": "N8FjcSWcQNeYCc-suM1O8g",
                    "account": "N8FjcSWcQNeYCc-suM1O8g",
                    "contact": {
                        "first": "Marcellus",
                        "last": "Walrus",
                        "email": "ne1@all.com",
                        "company": "Acme, Inc.",
                        "phone": null
                    },
                    "language": "en",
                    "country": "US",
                    "lookup": {
                        "global": "TVWhu0iwQhKJyuhpT_2yMw"
                    },
                    "url": "https://yourexamplestore.onfastspring.com/account"
                },
                "subscriptions": [],
                "subtractions": {
                    "tax": {
                        "currency": "USD",
                        "amount": 0,
                        "percentage": 0
                    },
                    "fastspring": {
                        "currency": "USD",
                        "amount": 5.3391,
                        "percentage": 8.9
                    }
                },
                "payouts": [
                    {
                        "payee": "exmaplepayee",
                        "currency": "USD",
                        "payout": "54.65",
                        "subtotal": 54.65,
                        "total": "59.99"
                    }
                ]
            },
            "event": "88qMx0P2RZCalzQ5ERXfXA"
        },
        {
            "id": "f_4YLUhbTPyaFhFPMKncWQ",
            "processed": false,
            "created": 1542239789431,
            "type": "order.completed",
            "live": false,
            "data": {
                "order": "EGr98BxdQ-idUfSZf_g-gw",
                "id": "EGr98BxdQ-idUfSZf_g-gw",
                "reference": "YES200314-8442-49161",
                "buyerReference": null,
                "completed": true,
                "changed": 1542239788922,
                "changedValue": 1542239788922,
                "changedInSeconds": 1542239788,
                "changedDisplay": "03/14/20",
                "language": "en",
                "live": false,
                "currency": "USD",
                "payoutCurrency": "USD",
                "invoiceUrl": "https://yourexamplestore.onfastspring.com/account/order/YES200314-8442-49161/invoice",
                "account": {
                    "id": "N8FjcSWcQNeYCc-suM1O8g",
                    "account": "N8FjcSWcQNeYCc-suM1O8g",
                    "contact": {
                        "first": "Marcellus",
                        "last": "Walrus",
                        "email": "ne1@all.com",
                        "company": "Acme, Inc.",
                        "phone": null
                    },
                    "language": "en",
                    "country": "US",
                    "lookup": {
                        "global": "TVWhu0iwQhKJyuhpT_2yMw"
                    },
                    "url": "https://yourexamplestore.onfastspring.com/account"
                },
                "total": 59.99,
                "totalDisplay": "$59.99",
                "totalInPayoutCurrency": 59.99,
                "totalInPayoutCurrencyDisplay": "$59.99",
                "tax": 0,
                "taxDisplay": "$0.00",
                "taxInPayoutCurrency": 0,
                "taxInPayoutCurrencyDisplay": "$0.00",
                "subtotal": 59.99,
                "subtotalDisplay": "$59.99",
                "subtotalInPayoutCurrency": 59.99,
                "subtotalInPayoutCurrencyDisplay": "$59.99",
                "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",
                    "cardEnding": "4242"
                },
                "customer": {
                    "first": "Marcellus",
                    "last": "Walrus",
                    "email": "ne1@all.com",
                    "company": "Acme, Inc.",
                    "phone": null
                },
                "address": {
                    "city": "Santa Barbara",
                    "regionCode": "CA",
                    "regionDisplay": "California",
                    "region": "California",
                    "postalCode": "93101",
                    "country": "US",
                    "display": "Santa Barbara, California, 93101, US"
                },
                "recipients": [
                    {
                        "recipient": {
                            "first": "Marcellus",
                            "last": "Walrus",
                            "email": "ne1@all.com",
                            "company": "Acme, Inc.",
                            "phone": null,
                            "account": {
                                "id": "N8FjcSWcQNeYCc-suM1O8g",
                                "account": "N8FjcSWcQNeYCc-suM1O8g",
                                "contact": {
                                    "first": "Marcellus",
                                    "last": "Walrus",
                                    "email": "ne1@all.com",
                                    "company": "Acme, Inc.",
                                    "phone": null
                                },
                                "language": "en",
                                "country": "US",
                                "lookup": {
                                    "global": "TVWhu0iwQhKJyuhpT_2yMw"
                                },
                                "url": "https://yourexamplestore.onfastspring.com/account"
                            },
                            "address": {
                                "city": "Santa Barbara",
                                "regionCode": "CA",
                                "regionDisplay": "California",
                                "region": "California",
                                "postalCode": "93101",
                                "country": "US",
                                "display": "Santa Barbara, California, 93101, US"
                            }
                        }
                    }
                ],
                "notes": [],
                "items": [
                    {
                        "product": "example-product-1",
                        "quantity": 1,
                        "display": "Example Product 1",
                        "sku": "skuex1",
                        "subtotal": 59.99,
                        "subtotalDisplay": "$59.99",
                        "subtotalInPayoutCurrency": 59.99,
                        "subtotalInPayoutCurrencyDisplay": "$59.99",
                        "discount": 0,
                        "discountDisplay": "$0.00",
                        "discountInPayoutCurrency": 0,
                        "discountInPayoutCurrencyDisplay": "$0.00",
                        "fulfillments": {
                            "example-product-1_file_2": [
                                {
                                    "display": "EXAMPLE.EXE",
                                    "size": 129,
                                    "file": "https://yourexamplestore.onfastspring.com/account/file/YES200314-8442-79162F"",
                                    "type": "file"
                                }
                            ],
                            "example-product-1_license_0": [
                                {
                                    "license": "Example-aw0r5H3YKBf8w9FNSqI2",
                                    "display": "License Key",
                                    "type": "license"
                                }
                            ],
                            "instructions": "Thank you for purchasing Example Product 1. To register, please launch the trial version and select Help | Register Examle Product 1. Then, copy and paste the license key above into the License Key field and click Submit."
                        }
                    }
                ]
            },
            "event": "f_4YLUhbTPyaFhFPMKncWQ"
        },
        {
            "id": "ik6eEaJHSlC-_ML8xzW5RQ",
            "processed": false,
            "created": 1542240018122,
            "type": "mailingListEntry.updated",
            "live": false,
            "data": {
                "id": "0cb4fdfbcf39be1eb6dd6c2032c8397fb7b60f604ba6094c6b261323a7641226",
                "list": "subscribed",
                "updated": 1542239788792,
                "reason": "subscribed",
                "order": {
                    "reference": "YES200314-8442-49161",
                    "id": "EGr98BxdQ-idUfSZf_g-gw",
                    "order": "EGr98BxdQ-idUfSZf_g-gw",
                    "items": [
                        {
                            "product": "example-product-1",
                            "quantity": 1,
                            "display": "Example Product 1",
                            "summary": "This is the **Summary** for Example Product 1",
                            "imageUrl": "https://d8y8nchqlnmka.cloudfront.net/VTetZH1kQD8/x4CxtvLjTBo/example-box.png""
                        }
                    ]
                },
                "email": "ne1@all.com",
                "firstName": "Marcellus",
                "lastName": "Walrus",
                "country": "US",
                "currency": "USD",
                "language": "en",
                "storefront": "yourexamplestore"
            },
            "event": "ik6eEaJHSlC-_ML8xzW5RQ"
        }
    ],
 "more": true
}
Possible Error Response Example
// No begin or days specified
{
  "action": "events.get",
  "result": "error",
  "error": {
    "begin": "Begin required."
  }
}


 
// Begin or days older than 30 days
{
  "action": "events.get",
  "result": "error",
  "error": {
    "begin": "Begin must be after '1488061077706' (Sat Feb 25 22:17:57 UTC 2017)."
  }
}


 
// Begin time later than the end time
{
  "action": "events.get",
  "result": "error",
  "error": {
    "begin": "Begin must be less than end."
  }

}


 
// Unparseable values
{
  "action": "events.get",
  "result": "error",
  "error": {
    "begin": "Can not parse begin",
    "end": "Can not parse end."

    "days": "Can not parse days."
  }

}

 

Update a Single Event

POST /events/{id}

   

Request Example
{
	"processed":true
}

Retrieve Missed or Unprocessed Events

In the event that your server does not process one or more events successfully (e.g., if your server is temporarily unavailable at the time an event is posted), you can repost them manually via the order or subscription details page, or retrieve any and all missed events by making a call to the /events/unprocessed endpoint of the FastSpring API.

Making a GET call to /events/unprocessed endpoint and all subscribed webhook events that have not been marked as processed (see above) will be returned in the API response. The response structure is nearly identical to the structures of the unprocessed webhook events, so you can process the response in the same way you would have processed the corresponding/missed webhook posts.

After processing any events that had been missed, you should mark those events as processed via a POST to the /events endpoint of the FastSpring API so that they will not be returned the next time you get unprocessed events. For example: POST /events/{id}.

The response returned from the /events endpoint is limited to 25 unique events. If the "more" attribute is present with a "true" value on the last line of the response, you may need to make multiple requests in order to retrieve all events. You can optionally specify a time frame with your request (e.g. beginning with the time of the last event in the response) if you want to page through all events before marking any of them processed.

It may be a good idea to set up an automatic, scheduled task that runs daily (or more often) on your servers to call /events/unprocessed and automatically retrieve any webhook events that might have been missed during the interval since the job last ran. After parsing the events, the script should mark them as processed. When retrieving unprocessed events, you can optionally specify a time frame, but that may not be necessary in this context.

This article provides information about the /coupons endpoint of the FastSpring API. Use this endpoint to create, update, delete, and get coupons.

 

Create a New Coupon or Edit an Existing One

POST /coupons

   

Request Example
{
    "coupon": "Black-Friday-2021",
    "discount": {
        "hasMultipleDiscounts": true,
        "discounts": [
            {
                "type": "flat",
                "amount": {
                    "USD": 10.0
                },
                "products": [
                    "saas-app-annual"
                ],
                "discountPeriodCount": null
            },
            {
                "type": "percent",
                "percent": 25.0,
                "products": [
                    "saas-app-monthly"
                ],
                "discountPeriodCount": 3
            }
        ]
    },
    "combine": false,
    "reason": {
        "en": "Black Friday Savings"
    },
    "limit": "",
    "available": {
        "start": "2021-11-24 ",
        "end": "2021-11-29 "
    },
    "codes": [
        "BF21",
        "BL21"
    ]
}
 
// For coupons with "percentage off" discount
 
// Use the same syntax as above but different type for "discount":
"discount": {"type": "percent", "percent": 20},

 

Update Existing Coupon

POST /coupons

   

Request Example
{
    "coupon": "coupon-id", // required, ID of the coupon you are updating
    "discount": {"type": "percent", "percent": 20},  // optional
    "combine": true, // "combine discounts" in the interface, optional.
    "reason": {"en": "String", "de": "String"}, //optional - an empty object {} will clear the reason.
    "limit": 10,  // optional - 0 will disable use-limit
    "available": {"start":"2015-08-15", "end": "2015-09-15"},  // optional - an empty object {} will clear both start date and end date; date and time must be supplied in UTC
    "codes": ["code1", "code2", ...]  //optional, an empty array [] will remove all existing coupon codes.
    "products": ["product-id", "another-product-id"] // optional - an empty array [] will remove all existing product conditions.
}

 

Add Coupon Codes to a Coupon

POST /coupons/{coupon-id}/codes

   

Request Example
{
 "codes": ["code1", "code2", ...]
}

 

Response Example
{
    "coupon": "holiday-2016",
    "codes": [
        "8675309"
    ],
    "result": "success"
}

// possible error response when trying to upload a duplicate code
{
    "coupon": "holiday-2016",
    "codes": [
        "0BXB6NMMCT",
        "0DCBKZN35L",
        "8675309"
    ],
    "result": "error",
    "error": "Coupon code 0BXB6NMMCT already exists."
}

 Note

If your request payload includes a duplicate of an existing coupon code, the response lists only the first duplicate code found. The API rejects the request, and any valid/non-duplicate codes included in the payload are not added to the coupon.

 

Retrieve Coupon Details

GET /coupons/{couponID}

   

Response Example
{
  "coupon": "blackfriday",              // coupon ID
  "discount": {
    "type": "percent",			// or "amount"
    "percent": 20			// discount value
  },
  "combine": false,			// can coupon discount be combined with product discounts?
  "reason": {
    "en": "Holiday Savings!"
  },				        // optional customer-facing "Applied Discount Reason" text
  "limit": "1",				// number of uses allowed per code
  "available": {
    "start": "2018-11-01 00:00",	// start date when the coupon will become available, in UTC
    "end": "2018-12-25 22:59"		// end date when coupon will expire, in UTC
  },
  "codes": [
    "0793PE2TSK",
    "0BXB6NMMCT",
    ...					// all remaining coupon codes will be listed
  ],
  "products": []			// if discounted is restricted to specific products, product IDs will be listed here
}

 

Get Coupon Codes Assigned to a Coupon

GET /coupons/{coupon-id}/codes

   

Request Example
{
 "codes": ["code1", "code2", ...]
}
Response Example
{
"coupon": "AXL", // coupon ID
"codes": ["AXL1"] // all coupon codes associated with the coupon ID, including both active and inactive codes
}

 

Delete ALL Coupon Codes from a Coupon

DELETE /coupons/{coupon-id}/codes

   

 WARNING

This request permanently deletes ALL remaining coupon codes from the specified coupon. After you make this request, the coupon will not have any codes remaining available. Customers will not be able to use the coupon until you add new codes.

The FastSpring API is a backend service you can use to communicate with your FastSpring Store programmatically. It requires basic understanding of HTTP communication methods. The primary API communication methods include:

The structure of the JSON data sent and received using the API is very similar to Webhooks. However, using the FastSpring API, you initiate all communication with your FastSpring Store.

As the merchant and seller of record for all the transactions we process, only FastSpring can collect consumers’ payment details. Because of this, there is no way to pass consumers’ payment details to FastSpring with the API.

 

If you prefer a client-side method of communicating with your FastSpring Store and generating dynamic webpage content, check out the Store Builder Library.

 

Access the API

API Credentials and Authentication

FastSpring API credentials consist of a single username and password for your entire Store. The username and password are used for Basic Authentication when making requests to the API.

Obtain Your API Credentials

  1. Log on to the FastSpring App and navigate to Integrations > API Credentials. Initially, the only option on this page is the Create command.


     

  2. Click Create to generate your API Username and Password. The page automatically refreshes, and then your credentials are displayed.


     

  3. Make a note of the credentials and store them securely.

The API credentials allow complete access and control over your FastSpring Store. You will not be able to view the password in the FastSpring App after this session. If you forget your API credentials, you can reset them, however any of your stored procedures that rely on API access must be updated immediately with the new credentials. Otherwise, the API requests will fail.

API Requests

Make all requests to https://api.fastspring.com

When you make your requests, consider the following:

Available API Endpoints

Endpoint Description Functions
/accounts  Work with customer accounts and FastSpring-generated account IDs
  • Get one account
  • Get all accounts
  • Create an account
  • Update an existing account
  • Look up accounts by parameters
  • Get authenticated account management URLs
/coupons Work with promotional coupons and their customer-facing codes Create a coupon
  • Update an existing coupon
  • Add coupon codes to a coupon
  • Retrieve coupon details
  • Get coupon codes assigned to a coupon
  • Delete coupon codes from a coupon
/events Retrieve unprocessed webhook events and mark events processed
  • Get processed or unprocessed webhook events matching specified parameters
/orders Work with order/transaction records
  • Get orders by ID
  • Get orders by product path
  • Get orders by date range
  • Update order tags and attributes
/products Work with product records
  • Get one or more products
  • Get a list of all product IDs
  • Create one or more new products
  • Update one or more existing products
/returns Work with returns and refunds
  • Get one or more returns by ID
/sessions Create a pre-loaded cart session for a specific customer with a FastSpring-generated account IDs; you can load the session in a Popup Storefront or provide the customer with a link to the session via a Web Storefront
  • Create a pre-filled order session
/subscriptions Work with customers' recurring-billing subscription instances Get all subscription instances
  • Get one or more specific subscription instances
  • Get subscription instance entries
  • Update existing subscription instances
  • Cancel subscription instances
  • Uncancel subscription instances before deactivation
  • Rebill managed subscription instances

Data Types

When preparing your database structure for storing values obtained from FastSpring via our JSON payloads, you might assume the following datatypes:

Rate Limits

To maintain a responsive user experience, FastSpring may impose request rate limits on API calls originating from individual accounts. If you encounter the rate limit, the response to the API request is an HTTP 404 response code.

Batch Requests

If you need to make a large number of API requests in a very short time, such that you may encounter rate limits, consider using batch requests where possible. For example, when retrieving authenticated account management URLs, you can obtain URLs for multiple account IDs in a single request:

GET /accounts/{id1}[,{id2},{id3},...]/authenticate

See /accounts for more details. Similar batch functionality is available for retrieving ordersproductsreturns, and subscriptions.

A session may contain discounts, price overrides, custom tags, and more. When you create a session via the FastSpring API, the response from the API includes the session ID, which you can use to collect payment. A customer cannot change the details of the session. A successful payment via the session creates an order record.

Session Behavior

An example to use the /sessions API endpoint is to provide customers with an option to pay what you want. Design your website to accept price data from your customers and use the /sessions endpoint to create a session that overrides the default prices. Alternatively, you can do this using a secure request via the Store Builder Library. Read more about the Order Flow.

Create a Session

POST /sessions

   

Example 1:  Create a Session Without Overriding Any Default Attributes

Request Example
{
   "account": "uKj7izONRfanVwBL9eiG_A",                // FastSpring-generated customer account ID (previously established via a prior order from this customer, or via the /accounts endpoint)
   "items": [
       {
           "product": "example-product-1",                        // product path of the product(s) to be included in the order
           "quantity": 1                               // quantity of the current product to be included in the order
       }
   ]
}
Response Example
{
  "id": "FnE_y0t9R_WF5b2W0DI72Q",                      // session ID to be used in customer-facing URL or fastspring.builder.checkout("sessionID");
  "currency": "USD",
  "expires": 1490109872476,
  "order": null,
  "account": "uKj7izONRfanVwBL9eiG_A",
  "subtotal": 9.95,
  "items": [
    {
      "product": "example-product-1",
      "quantity": 1
    }
  ]
}

 

Example 2:  Override a Product's Default Pricing

Request Example
{
   "account": "uKj7izONRfanVwBL9eiG_A",                // FastSpring-generated customer account ID (previously established via a prior order from this customer, or via the /accounts endpoint)
   "items": [
       {
           "product": "example-product-1",                        // product path of the product(s) to be included in the order
           "quantity": 1,                              // quantity of the current product to be included in the order
           "pricing": {
               "price": {
                   "USD": 10.00                        // other currencies supported by the Store may be specified
               }
           }
       }
   ]
}
Response Example
{
  "id": "Up_M3u20QA-fyeM2Sv-0uA",                      // session ID to be used in customer-facing URL or fastspring.builder.checkout("sessionID");
  "currency": "USD",
  "expires": 1482355186169,
  "order": null,
  "account": "uKj7izONRfanVwBL9eiG_A",
  "subtotal": 10,
  "items": [
    {
      "product": "example-product-1",
      "quantity": 1
    }
  ]
}

 

Example 3:  Apply a Coupon to an Order

Request Example
{
   "account": "uKj7izONRfanVwBL9eiG_A",                // FastSpring-generated customer account ID (previously established via a prior order from this customer, or via the /accounts endpoint)
   "items": [
       {
           "product": "example-product-2",                          // product path of the product(s) to be included in the order
           "quantity": 2                               // quantity of the current product to be included in the order
       }
   ],
   "coupon": "0BXB6NMMCT"                              // coupon code (not coupon ID) to be applied to the order 
}
Response Example
{
  "id": "c7OY_bnCTSuUlwPHq1BMhg",                      // session ID to be used in customer-facing URL or fastspring.builder.checkout("sessionID");
  "currency": "USD",
  "expires": 1482355423050,
  "order": null,
  "account": "uKj7izONRfanVwBL9eiG_A",
  "subtotal": 7.92,
  "items": [
    {
      "product": "example-product-2",
      "quantity": 2
    }
  ]
}

 

Example 4:  Apply a Product-Level Discount (Not a Coupon) to a Subscription Order for the Initial Transaction Only

Request Example
{  
  "account":"N8FjcSWcQNeYCc-suM1O8g",                  // FastSpring-generated customer account ID (previously established via a prior order from this customer, or via the /accounts endpoint)
  "items":[  
    {  
      "product":"example-monthly-subscription",        // product path of the product(s) to be included in the order
      "quantity":1,                                    // quantity of the current product to be included in the order
      "pricing":{  
        "renew":"auto",
        "interval":"month",
        "intervalLength":1,
        "intervalCount":3,
        "upcomingProduct":null,
        "quantityBehavior":"allow",
        "quantityDefault":1,
        "price":{  
          "USD":10.00
        },
        "quantityDiscounts":{  
          "1":                                         // this object indicates that the specified discount applies even when the quantity is one; additional discounts could be applied at other quantity levels
          {
            "USD":2
          }
        },
        "discountDuration":1                           // the discountDuration of 1 means the discount will only apply to the initial charge; you would enter 2 for the initial charge and first rebill, and so on
      }
    }
  ]
}
Response Example
{  
  "id":"qK_Xnc-kQHK_eYVZLlzAig",                       // session ID to be used in customer facing URL or fastspring.builder.checkout("sessionID")
  "currency":"USD",
  "expires":1558813994056,
  "order":null,
  "account":"N8FjcSWcQNeYCc-suM1O8g",
  "subtotal":8,
  "items":[  
    {  
      "product":"example-monthly-subscription",
      "quantity":1
    }
  ]
}

 

Example 5:  Specify or Override a One-Time Setup Fee for a Subscription Product

Request Example
{
   "account": "uKj7izONRfanVwBL9eiG_A",                // FastSpring-generated customer account ID (previously established via a prior order from this customer, or via the /accounts endpoint)
   "items": [
       {
           "product": "example-monthly-subscription",  // product path of the product(s) to be included in the order
           "quantity": 1,                              // quantity of the current product to be included in the order
           "pricing": {
              "setupFee": {                            // subscription one-time setup fee
                "title": {                             // customer-facing description of the one-time setup fee
                   "en": "Subscription Initiation Fee"
                },
                "price": {                             // amount of the one-time setup fee
                   "USD":10.00
                }
              }
           }
       }
   ]
}
Response Example
{
    "id": "-1sHIQliSQGKGvF6vJWb0g",
    "currency": "USD",
    "expires": 1572726026353,
    "order": null,
    "account": "uKj7izONRfanVwBL9eiG_A",
    "subtotal": 24.95,
    "items": [
        {
            "product": "example-monthly-subscription",
            "quantity": 1
        },
        {
            "product": "example-monthly-subscription.setupFee",
            "quantity": 1
        }
    ]
}

 

Possible Error Responses

Error Response Example
Response
400
{
  "message": "Can not parse request body.",            // invalid or malformed JSON object in request
  "params": []
}

 
Response
400
{
  "message": "invalid",                                // request includes an invalid value
  "params": [
    "coupon"                                           // name of the value that is not valid (e.g. for an invalid coupon code)
  ]
}
 
 
Response
400
{  
   "message":"Item exists",                            // attempted to add the same product path twice in the same request; this includes product variations associated with a product already in the request (and vice versa)
   "params":[  
      "example-product-1"                                         // product path of duplicated item
   ]
}
 
 
Response
400
{
  "message": "Item not found",                         // product path not found / invalid
  "params": [
    "exampl-product-1"                                           // path of the invalid / not found product
  ]
}


Response
400
{                                                                            
  "message": "required",                               // missing or invalid required parameter
  "params": [
    "account"                                          // name of the missing or invalid parameter (account = account ID)
  ]
}

 

Deploy a Session for Payment via a Web Storefront

To have the customer purchase using the session via your Web Storefront, append /session/<sessionID> to the Storefront's Homepage URL and then provide the URL to the customer.

For example, if your Web Storefront's Homepage URL is https://yourexamplestore.onfastspring.com and your session ID is k5l1ezPuSBa_Mo7u1_RS1w, the URL would be:

https://yourexamplestore.onfastspring.com/session/k5l1ezPuSBa_Mo7u1_RS1w

Upon visiting the link, the customer will see your Web Storefront with the cart already defined based on the parameters you passed into the session. For example, if you passed in a coupon code as in example 3 above, the coupon will already be applied to the order:

Upon selecting a payment method, the information shown to (and required from) the customer will be limited based on the information already "known" to FastSpring for the account ID that you passed into the session. For example, the customer's name and email address will not be required.

Deploy a Session for Payment via a Popup Storefront

To have the customer purchase using the session via your Popup Storefront, simply pass the session ID obtained in the API response into the fastspring.builder.checkout("<sessionID>") method.

For example, if your session ID is s9vP7-LmR3KJuAAAhjTYcw, the method would be fastspring.builder.checkout("s9vP7-LmR3KJuAAAhjTYcw").

Upon making the call in the customer's Web browser (e.g., on a page on your web site), the customer will see a standard Popup Storefront modal checkout window. However, the information shown to (and required from) the customer will be limited based on the information already "known" to FastSpring for the account ID that you passed into the session. For example, the customer's name and email address will not be required.

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.

Request Parameters

Parameter Values Description
begin  yyyy-mm-dd filters results to include transactions after the specified begin date (must be at least one day before the specified end date)
days integer filters results to include transactions within a certain time frame
end yyyy-mm-dd filters results to include transactions before the specified end date
limit integer integer limits the number of order records returned per page (default is 50 records)
page integer specifies page number of results to be returned; used together with limit to control pagination
products string filters results to include only transactions involving the specified product ID(s) / product path(s)
rebill true/false filters results to include only subscription rebill transactions or exclude all subscription rebill transactions
returns true/false filters results to include orders with or without returns; response includes returns array with return IDs where applicable
scope all, live, test filters results to include live transactions, test transactions, or both
status completed, canceled, failed filters results by transaction status; "completed" = successful orders, "canceled" = declined orders, "failed" = transaction failed to complete (very uncommon)

Example 1:  Get orders by ID

GET /orders/{id1},{id2},{id3},...
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"
      }
    }  
  ]
}

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"
         }
         ]
      }
     ...
    ]
  }

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"
  }
}

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": {}
            }
         ]
      }
      ...
    ]
  }

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"
         }]
      }
      ...	  
    ]
  }

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
Updating order tags or product attributes replaces the current order tags or attributes. Subscription webhooks and API responses automatically pull order tags and product attributes from the original 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"
            }
        }
    ]
}