order.approval.pending

Last modified January 29, 2019

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

The order.approval.pending server webhook event is fired when approval is required before an order can be completed (for example, 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 will include the full customer account object rather than just the account ID.

Contents of Event Payload

NameTypeDescription
orderstringinternal order ID
idstringinternal order ID
referencestringcustomer-visible order reference
buyerReferencestringoptional purchase order number entered by the customer
completedBoolean"true" for a completed order; never true for order.approval.pending
changedintegerdate of the most recent update to the order record, in milliseconds
changedValueintegerdate of the most recent update to the order record, in milliseconds
(backward compatibility)
changedInSecondsintegerdate of the most recent update to the order record, in seconds
changedDisplaystringdate of the most recent update to the order record, formatted for display based on the
language in which the order was processed
languagestringtwo-character ISO code for the order language
liveBoolean"false" for a test order
currencystringthree-character ISO code for the order currency
payoutCurrencystringthree-character ISO code for the currency in which your disbursement will be made
invoiceUrlstringURL of the customer-facing invoice for this order
accountstring (expansion disabled)
object (expansion enabled)
FastSpring-generated customer account ID (expansion disabled)
details of the customer account (expansion enabled)
account.idstringFastSpring-generated customer account ID
account.accountstringFastSpring-generated customer account ID
account.contactobjectcustomer's contact details
account.contact.firststringcustomer's first name
account.contact.laststringcustomer's last name
account.contact.emailstringcustomer's email address
account.contact.companystringcustomer's company name
account.contact.phonestringcustomer's telephone number
account.languagestringtwo-character ISO code for the language associated with the customer's account
account.countrystringtwo-character ISO code for the country associated with the customer's account
account.lookupobjectmultiple-field object containing lookup IDs for the customer account (e.g. for use with the /accounts endpoint of the FastSpring API)
account.lookup.globalstringexternal customer account ID, generated by FastSpring
account.urlstringurl for the Store's default account management page
totalnumberorder total in the transaction's currency
totalDisplaystringorder total, formatted for display in the transaction's currency
totalInPayoutCurrencynumberorder total in the currency of your FastSpring disbursements
totalInPayoutCurrencyDisplaystringorder total, formatted for display in the currency of your FastSpring disbursements
taxnumberamount of tax
taxDisplaystringamount of tax, formatted for display in the transaction's currency
taxInPayoutCurrencynumberamount of tax in the currency of your FastSpring disbursements
taxInPayoutCurrencyDisplaystringamount of tax, formatted for display in the currency of your FastSpring disbursements
subtotalnumberorder subtotal in the transaction's currency
subtotalDisplaystringorder subtotal, formatted for display in the transaction's currency
subtotalInPayoutCurrencynumberorder subtotal in the currency of your FastSpring disbursements
subtotalInPayoutCurrencyDisplaystringorder subtotal, formatted for display in the currency of your FastSpring disbursements
discountnumbertotal discount applied to the order in the transaction's currency
discountDisplaystringtotal discount applied to the order, formatted for display in the transaction's currency
discountInPayoutCurrencynumbertotal discount applied to the order, in the currency of your FastSpring disbursements
discountInPayoutCurrencyDisplaystringtotal discount applied to the order, formatted for display in the currency of your FastSpring disbursements
discountWithTaxnumberdiscount amount including tax
discountWithTaxDisplaystringdiscount amount including tax, formatted for display in the transaction's currency
discountWithTaxInPayoutCurrencynumberdiscount amount including tax, in the currency of your FastSpring disbursements
discountWithTaxInPayoutCurrencyDisplaystringdiscount amount including tax, formatted for display in the currency of your FastSpring disbursements
billDescriptorstringthe description information sent to the payment account for display on the customer's statement (always "N/A" for this event)
paymentobjectnormally contains details about the transaction's payment method, but blank here since the payment has not been completed yet
reasonstringreason approval is required for the order (e.g. purchaseOrder)
customerobjectdetails about the customer
customer.firststringcustomer's first name
customer.laststringcustomer's last name
customer.emailstringcustomer's email address
customer.companystringcustomer's company name
customer.phonestringcustomer's telephone number
addressobjectdetails about the customer address associated with this order
address.citystringname of the city in the address
address.regionCodestringtwo-character ISO code for the state of the address (present for U.S. addresses only)
address.regionDisplaystringstate or region of the address, formatted for display
address.regionstringstate or region of the address (backward compatibility)
address.postalCodestringpostal code of the address
address.countrystringcountry of the address
address.displaystringconcatenated string of address information, formatted for display
recipientsarraydetails on the customer and / or the recipient of gift purchases; for non-gift purchases, info will be the same as order.customer and order.address info
recipients.recipientobjectobject containing all details of the current recipient in the array
recipients.recipient.firststringrecipient's first name
recipients.recipient.laststringrecipient's last name
recipients.recipient.emailstringrecipient's email address
recipients.recipient.companystringrecipient's company (optional)
recipients.recipient.phonestringrecipient's phone number
recipients.recipient.accountstring (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.idstringrecipient's FastSpring-generated customer account ID
recipients.recipient.account.accountstringrecipient's FastSpring-generated customer account ID (backward compatibility)
recipients.recipient.account.contactobjectrecipient's contact details
recipients.recipient.account.contact.firststringrecipient's first name
recipients.recipient.account.contact.laststringrecipient's last name
recipients.recipient.account.contact.emailstringrecipient's email address
recipients.recipient.account.contact.companystringrecipient's company name
recipients.recipient.account.contact.phonestringrecipient's telephone number
recipients.recipient.account.languagestringtwo-character ISO code for the language associated with the recipient's account
recipients.recipient.account.countrystringtwo-character ISO code for the country associated with the recipient's account
recipients.recipient.account.lookupobjectmultiple-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.globalstringrecipient's external customer account ID, generated by FastSpring
recipients.recipient.account.lookup.customstringoptional custom account ID specified via the /accounts endpoint of the FastSpring API (not shown in examples below)
recipients.recipient.account.urlstringurl for the Store's default account management page
recipients.recipient.addressobjectmutli-line object containing recipient address information
recipients.recipient.address.addressLine1stringrecipient's street address (when a physical product was in the order or "Force physical address collection" was enabled)
recipients.recipient.address.citystringrecipient's city
recipients.recipient.address.regionCodestringtwo-character ISO code for the state of the address (present for U.S. addresses only)
recipients.recipient.address.regionDisplaystringstate or region of the address, formatted for display
recipients.recipient.address.regionstringstate or region of the address
recipients.recipient.address.postalCodestringpostal code of the address
recipients.recipient.address.countrystringcountry of the address
recipients.recipient.address.displaystringconcatenated string of address information, formatted for display
notesarrayoptional internal order notes entered via Dashboard
itemsarrayproducts included in the order, one object per product
items.productstringproduct path / product ID
items.quantityintegerquantity of the current product in this transaction
items.displaystringcustomer-facing Display name of the product
items.skustringoptional internal SKU ID (e.g. your part number) for the current product
items.subtotalnumbersubtotal for the current product, in the transaction's currency
items.subtotalDisplaystringsubtotal for the current product, formatted for display in the transaction's currency
items.subtotalInPayoutCurrencynumbersubtotal for the current product, in the currency of your FastSpring disbursements
items.subtotalInPayoutCurrencyDisplaystringsubtotal for the current product, formatted for display in the currency of your FastSpring disbursements
items.attributesobjectmultiple-field object containing optional product-level attributes for the current product
items.discountnumberamount of any discount applied to the current product
items.discountDisplaystringamount of any discount applied to the current product, formatted for display in the transaction's currency
items.discountInPayoutCurrencynumberamount of any discount applied to the current product, in the currency of your FastSpring disbursements
items.discountInPayoutCurrencyDisplaystringamount of any discount applied to the current product, formatted for display in the currency of your FastSpring disbursements
items.fulfillmentsobjectmultiple-field object containing details of fulfillment actions associated with the current product (file, license, or instructions)
items.driverobjectwhen 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.typestringrelationship to parent / triggering item (e.g. "cross-sell", "bundle", "configuration")
items.driver.pathstringproduct 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)
couponsarraylist 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":"FUR190121-7019-29124",
   "buyerReference":null,
   "completed":false,
   "changed":1548093006664,
   "changedValue":1548093006664,
   "changedInSeconds":1548093006,
   "changedDisplay":"1/21/19",
   "language":"en",
   "live":false,
   "currency":"USD",
   "payoutCurrency":"USD",
   "invoiceUrl":"https://furiousfalcon.onfastspring.com/account/order/FUR190121-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":"falcon",
         "quantity":1,
         "display":"Furious Falcon",
         "sku":"falcon6abc123",
         "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":"<p>Thank you for purchasing <em>Falcon</em>. To register, please launch the trial version and select <strong>Help</strong> | <strong>Register Falcon</strong>. Then, copy and paste the license key above into the <strong>License Key</strong> field and click <strong>Submit</strong>.</p>"
         }
      }
   ]
}


Example 2 - Webhook Expansion Enabled

order.approval.pending webhook example (webhook expansion enabled)
{  
   "order":"jXoNVMcGSwi-W66c5A_HPA",
   "id":"jXoNVMcGSwi-W66c5A_HPA",
   "reference":"FUR190121-7019-53108",
   "buyerReference":"OICU812",
   "completed":false,
   "changed":1548091747153,
   "changedValue":1548091747153,
   "changedInSeconds":1548091747,
   "changedDisplay":"1/21/19",
   "language":"en",
   "live":false,
   "currency":"USD",
   "payoutCurrency":"USD",
   "invoiceUrl":"https://furiousfalcon.onfastspring.com/account/order/FUR190121-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://furiousfalcon.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://furiousfalcon.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":"falcon",
         "quantity":1,
         "display":"Furious Falcon",
         "sku":"falcon6abc123",
         "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":"<p>Thank you for purchasing <em>Falcon</em>. To register, please launch the trial version and select <strong>Help</strong> | <strong>Register Falcon</strong>. Then, copy and paste the license key above into the <strong>License Key</strong> field and click <strong>Submit</strong>.</p>"
         }
      }
   ]
}