Collapse Menu
Documentation
FastSpring App
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.

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:

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

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

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.