Collapse Menu
Docs Home
Extensibility Options
Contact Support

/events

Overview

This article provides information about the /events endpoint of the FastSpring API. Use this endpoint to retrieve the payloads for passed webhook events.

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:

  • Your Store goes live on Sunday, and you do not subscribe to the order.completed webhook event.
  • On Monday, a customer places an order.
  • On Tuesday, you subscribe to the order.completed event.
  • On Wednesday, a second customer places an order.

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

  • ?days=5 - Events from the last 5 days
  • ?begin=unixtime&end=unixtime

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/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:

  • the event ID
  • the event's processed status
  • the event's created date
  • type indicator that identifies the event type (e.g., order.canceled)
  • a separate indication as to whether or not the referenced event was in live mode (i.e., not test mode).
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
}

Try FastSpring

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