order.approval.pending
Overview
This article provides details about the order.approval.pending webhook event.
The order.approval.pending server webhook event fires when approval is required before an order can be completed. For example, the event fires when purchase orders are enabled for your Store with the Require Approval method configured, and a buyer places an order using a purchase order.
About Webhook Expansion
When webhook expansion is enabled, order.approval.pending includes the full customer account object rather than just the account ID.IMPORTANT
Each post from FastSpring to your endpoint may contain more than one webhook event in its payload. For more information, please see About Webhooks.
Contents of Event Payload
| Name | Type | Description |
| order | string | internal order ID |
| id | string | internal order ID |
| reference | string | customer-visible order reference |
| buyerReference | string | optional purchase order number entered by the customer |
| ipAddress | number | the customer's apparent IP address |
| completed | Boolean | "true" for a completed order; never true for order.approval.pending |
| changed | integer | date of the most recent update to the order record, in milliseconds |
| changedValue | integer | date of the most recent update to the order record, in milliseconds (backward compatibility) |
| changedInSeconds | integer | date of the most recent update to the order record, in seconds |
| changedDisplay | string | date of the most recent update to the order record, formatted for display based on the language in which the order was processed |
| language | string | two-character ISO code for the order language |
| live | Boolean | "false" for a test order |
| currency | string | three-character ISO code for the order currency |
| payoutCurrency | string | three-character ISO code for the currency in which your disbursement will be made |
| invoiceUrl | string | URL of the customer-facing invoice for this order |
| account | string (expansion disabled) object (expansion enabled) | FastSpring-generated customer account ID (expansion disabled) details of the customer account (expansion enabled) |
| account.id | string | FastSpring-generated customer account ID |
| account.account | string | FastSpring-generated customer account ID |
| account.contact | object | customer's contact details |
| account.contact.first | string | customer's first name |
| account.contact.last | string | customer's last name |
| account.contact.email | string | customer's email address |
| account.contact.company | string | customer's company name |
| account.contact.phone | string | customer's telephone number |
| account.language | string | two-character ISO code for the language associated with the customer's account |
| account.country | string | two-character ISO code for the country associated with the customer's account |
| account.lookup | object | multiple-field object containing lookup IDs for the customer account (e.g., for use with the /accounts endpoint of the FastSpring API) |
| account.lookup.global | string | external customer account ID, generated by FastSpring |
| account.url | string | URL for the Store's default account management page |
| total | number | order total in the transaction's currency |
| totalDisplay | string | order total, formatted for display in the transaction's currency |
| totalInPayoutCurrency | number | order total in the currency of your FastSpring disbursements |
| totalInPayoutCurrencyDisplay | string | order total, formatted for display in the currency of your FastSpring disbursements |
| tax | number | amount of tax |
| taxDisplay | string | amount of tax, formatted for display in the transaction's currency |
| taxInPayoutCurrency | number | amount of tax in the currency of your FastSpring disbursements |
| taxInPayoutCurrencyDisplay | string | amount of tax, formatted for display in the currency of your FastSpring disbursements |
| subtotal | number | order subtotal in the transaction's currency |
| subtotalDisplay | string | order subtotal, formatted for display in the transaction's currency |
| subtotalInPayoutCurrency | number | order subtotal in the currency of your FastSpring disbursements |
| subtotalInPayoutCurrencyDisplay | string | order subtotal, formatted for display in the currency of your FastSpring disbursements |
| discount | number | total discount applied to the order in the transaction's currency |
| discountDisplay | string | total discount applied to the order, formatted for display in the transaction's currency |
| discountInPayoutCurrency | number | total discount applied to the order, in the currency of your FastSpring disbursements |
| discountInPayoutCurrencyDisplay | string | total discount applied to the order, formatted for display in the currency of your FastSpring disbursements |
| discountWithTax | number | discount amount including tax |
| discountWithTaxDisplay | string | discount amount including tax, formatted for display in the transaction's currency |
| discountWithTaxInPayoutCurrency | number | discount amount including tax, in the currency of your FastSpring disbursements |
| discountWithTaxInPayoutCurrencyDisplay | string | discount amount including tax, formatted for display in the currency of your FastSpring disbursements |
| billDescriptor | string | the description information sent to the payment account for display on the customer's statement (always "N/A" for this event) |
| payment | object | usually contains details about the transaction's payment method, but blank here since the payment is not yet complete |
| reason | string | reason approval is required for the order (e.g., purchaseOrder) |
| customer | object | details about the customer |
| customer.first | string | customer's first name |
| customer.last | string | customer's last name |
| customer.email | string | customer's email address |
| customer.company | string | customer's company name |
| customer.phone | string | customer's telephone number |
| address | object | details about the customer address associated with this order |
| address.city | string | name of the city in the address |
| address.regionCode | string | two-character ISO code for the state of the address (present for U.S. addresses only) |
| address.regionDisplay | string | state or region of the address, formatted for display |
| address.region | string | state or region of the address (backward compatibility) |
| address.postalCode | string | postal code of the address |
| address.country | string | country of the address |
| address.display | string | concatenated string of address information, formatted for display |
| recipients | array | details on the purchaser or the recipient of gift purchases; for non-gift purchases, info will be the same as order.customer and order.address info |
| recipients.recipient | object | object containing all details of the current recipient in the array |
| recipients.recipient.first | string | recipient's first name |
| recipients.recipient.last | string | recipient's last name |
| recipients.recipient.email | string | recipient's email address |
| recipients.recipient.company | string | recipient's company (optional) |
| recipients.recipient.phone | string | recipient's phone number |
| recipients.recipient.account | string (expansion disabled) object (expansion enabled) | recipient's FastSpring-generated customer account ID (expansion disabled) details of the recipient's customer account (expansion enabled) |
| recipients.recipient.account.id | string | recipient's FastSpring-generated customer account ID |
| recipients.recipient.account.account | string | recipient's FastSpring-generated customer account ID (backward compatibility) |
| recipients.recipient.account.contact | object | recipient's contact details |
| recipients.recipient.account.contact.first | string | recipient's first name |
| recipients.recipient.account.contact.last | string | recipient's last name |
| recipients.recipient.account.contact.email | string | recipient's email address |
| recipients.recipient.account.contact.company | string | recipient's company name |
| recipients.recipient.account.contact.phone | string | recipient's telephone number |
| recipients.recipient.account.language | string | two-character ISO code for the language associated with the recipient's account |
| recipients.recipient.account.country | string | two-character ISO code for the country associated with the recipient's account |
| recipients.recipient.account.lookup | object | multiple-field object containing lookup IDs for the recipient's customer account (e.g., for use with the /accounts endpoint of the FastSpring API) |
| recipients.recipient.account.lookup.global | string | recipient's external customer account ID, generated by FastSpring |
| recipients.recipient.account.lookup.custom | string | optional custom account ID specified via the /accounts endpoint of the FastSpring API (not shown in examples below) |
| recipients.recipient.account.url | string | url for the Store's default account management page |
| recipients.recipient.address | object | mutli-line object containing recipient address information |
| recipients.recipient.address.addressLine1 | string | recipient's street address (when a physical product was in the order or "Force physical address collection" was enabled) |
| recipients.recipient.address.city | string | recipient's city |
| recipients.recipient.address.regionCode | string | two-character ISO code for the state of the address (present for U.S. addresses only) |
| recipients.recipient.address.regionDisplay | string | state or region of the address, formatted for display |
| recipients.recipient.address.region | string | state or region of the address |
| recipients.recipient.address.postalCode | string | postal code of the address |
| recipients.recipient.address.country | string | country of the address |
| recipients.recipient.address.display | string | concatenated string of address information, formatted for display |
| notes | array | optional internal order notes entered via Dashboard |
| items | array | products included in the order, one object per product |
| items.product | string | product path/product ID |
| items.quantity | integer | quantity of the current product in this transaction |
| items.display | string | customer-facing Display name of the product |
| items.sku | string | optional internal SKU ID (e.g., your part number) for the current product |
| items.subtotal | number | subtotal for the current product, in the transaction's currency |
| items.subtotalDisplay | string | subtotal for the current product, formatted for display in the transaction's currency |
| items.subtotalInPayoutCurrency | number | subtotal for the current product, in the currency of your FastSpring disbursements |
| items.subtotalInPayoutCurrencyDisplay | string | subtotal for the current product, formatted for display in the currency of your FastSpring disbursements |
| items.attributes | object | multiple-field object containing optional product-level attributes for the current product |
| items.discount | number | amount of any discount applied to the current product |
| items.discountDisplay | string | amount of any discount applied to the current product, formatted for display in the transaction's currency |
| items.discountInPayoutCurrency | number | amount of any discount applied to the current product, in the currency of your FastSpring disbursements |
| items.discountInPayoutCurrencyDisplay | string | amount of any discount applied to the current product, formatted for display in the currency of your FastSpring disbursements |
| items.fulfillments | object | multiple-field object containing details of fulfillment actions associated with the current product (file, license, or instructions) |
| items.driver | object | when the current item was sold as a cross-sell or an upsell, or when the current item is a bundle child, indicates relationship to driving product |
| items.driver.type | string | relationship to parent / triggering item (e.g. "cross-sell", "bundle", "configuration") |
| items.driver.path | string | product path / ID of parent / triggering item; when type = "cross-sell" this indicates the triggering item; when type = "bundle" this indicates in the bundle parent, meaning that the current item is a child of the specified bundle product when type = "configuration" this indicates the triggering item (as with a cross-sell) |
| coupons | array | list of coupon IDs applied to the order (currently, only one coupon can be applied to an order) |
Examples
Example 1 - Webhook Expansion Disabled
order.approval.pending webhook example (webhook expansion disabled)
{
"order":"8FqrTAgJRSKSQI3djH90eQ",
"id":"8FqrTAgJRSKSQI3djH90eQ",
"reference":"YES200316-7019-29124",
"buyerReference":null,
"ipAddress": "000.000.00.000",
"completed":false,
"changed":1548093006664,
"changedValue":1548093006664,
"changedInSeconds":1548093006,
"changedDisplay":"1/21/19",
"language":"en",
"live":false,
"currency":"USD",
"payoutCurrency":"USD",
"invoiceUrl":"https://yourexamplestore.onfastspring.com/account/order/YES200316-7019-29124/invoice",
"account":"N8FjcSWcQNeYCc-suM1O8g",
"total":59.99,
"totalDisplay":"$59.99",
"totalInPayoutCurrency":59.99,
"totalInPayoutCurrencyDisplay":"$59.99",
"tax":0.0,
"taxDisplay":"$0.00",
"taxInPayoutCurrency":0.0,
"taxInPayoutCurrencyDisplay":"$0.00",
"subtotal":59.99,
"subtotalDisplay":"$59.99",
"subtotalInPayoutCurrency":59.99,
"subtotalInPayoutCurrencyDisplay":"$59.99",
"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":"N/A",
"payment":{
},
"reason":"purchaseOrder",
"customer":{
"first":"Lieutenant",
"last":"Wharf",
"email":"ne1@all.com",
"company":"United Federation of Places",
"phone":"8054099008"
},
"address":{
"addressLine1":"801 Garden Street",
"city":"Santa Barbara",
"regionCode":"CA",
"regionDisplay":"California",
"region":"California",
"postalCode":"93101",
"country":"US",
"display":"801 Garden Street, Santa Barbara, California, 93101, US"
},
"recipients":[
{
"recipient":{
"first":"Lieutenant",
"last":"Wharf",
"email":"ne1@all.com",
"company":"United Federation of Places",
"phone":"8054099008",
"account":"N8FjcSWcQNeYCc-suM1O8g",
"address":{
"addressLine1":"801 Garden Street",
"city":"Santa Barbara",
"regionCode":"CA",
"regionDisplay":"California",
"region":"California",
"postalCode":"93101",
"country":"US",
"display":"801 Garden Street, 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",
"attributes":{
"season":"of the forge"
},
"discount":0.0,
"discountDisplay":"$0.00",
"discountInPayoutCurrency":0.0,
"discountInPayoutCurrencyDisplay":"$0.00",
"fulfillments":{
"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."
}
}
]
}
Example 2 - Webhook Expansion Enabled
order.approval.pending webhook example (webhook expansion enabled)
{
"order":"jXoNVMcGSwi-W66c5A_HPA",
"id":"jXoNVMcGSwi-W66c5A_HPA",
"reference":"YES200316-7019-53108",
"buyerReference":"OICU812",
"ipAddress": "000.000.00.000",
"completed":false,
"changed":1548091747153,
"changedValue":1548091747153,
"changedInSeconds":1548091747,
"changedDisplay":"1/21/19",
"language":"en",
"live":false,
"currency":"USD",
"payoutCurrency":"USD",
"invoiceUrl":"https://yourexamplestore.onfastspring.com/account/order/200316-7019-53108/invoice",
"account":{
"id":"N8FjcSWcQNeYCc-suM1O8g",
"account":"N8FjcSWcQNeYCc-suM1O8g",
"contact":{
"first":"Blogodan",
"last":"Juriosevicizki",
"email":"ne1@all.com",
"company":"Acme",
"phone":"8054099008"
},
"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.0,
"taxDisplay":"$0.00",
"taxInPayoutCurrency":0.0,
"taxInPayoutCurrencyDisplay":"$0.00",
"subtotal":59.99,
"subtotalDisplay":"$59.99",
"subtotalInPayoutCurrency":59.99,
"subtotalInPayoutCurrencyDisplay":"$59.99",
"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":"N/A",
"payment":{
},
"reason":"purchaseOrder",
"customer":{
"first":"Blogodan",
"last":"Juriosevicizki",
"email":"ne1@all.com",
"company":"Acme",
"phone":"8054099008"
},
"address":{
"addressLine1":"801 Garden Street",
"city":"Santa Barbara",
"regionCode":"CA",
"regionDisplay":"California",
"region":"California",
"postalCode":"93101",
"country":"US",
"display":"801 Garden Street, Santa Barbara, California, 93101, US"
},
"recipients":[
{
"recipient":{
"first":"Blogodan",
"last":"Juriosevicizki",
"email":"ne1@all.com",
"company":"Acme",
"phone":"8054099008",
"account":{
"id":"N8FjcSWcQNeYCc-suM1O8g",
"account":"N8FjcSWcQNeYCc-suM1O8g",
"contact":{
"first":"Blogodan",
"last":"Juriosevicizki",
"email":"ne1@all.com",
"company":"Acme",
"phone":"8054099008"
},
"language":"en",
"country":"US",
"lookup":{
"global":"TVWhu0iwQhKJyuhpT_2yMw"
},
"url":"https://yourexamplestore.onfastspring.com/account"
},
"address":{
"addressLine1":"801 Garden Street",
"city":"Santa Barbara",
"regionCode":"CA",
"regionDisplay":"California",
"region":"California",
"postalCode":"93101",
"country":"US",
"display":"801 Garden Street, 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",
"attributes":{
"season":"of the forge"
},
"discount":0.0,
"discountDisplay":"$0.00",
"discountInPayoutCurrency":0.0,
"discountInPayoutCurrencyDisplay":"$0.00",
"fulfillments":{
"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."
}
}
]
}