FastSpring AppAPI ReferenceWebhooksFastSpring JSChangelogFastSpring.com
Developer Documentation
Sign In

Approve a Purchase Order

order.approval.pending

Overview of the order.approval.pending webhook

When an order.approval.pending event is triggered, FastSpring sends a webhook payload containing details about the order awaiting approval. This webhook fires only when you've enabled the Invoicing Service with purchase-order approval required and a customer submits a PO.

If webhook expansion is enabled, the payload includes full account and product objects. Otherwise, the payload includes only the corresponding IDs.

This page provides:

  • A full sample payload showing a populated order.approval.pending webhook
  • A detailed table listing every payload property, including name, type, and description
  • Notes on when this webhook is triggered and which fields appear based on Webhook Expansion

Browse the table sections below or use the quick links to jump to a specific group of fields.

Tip: Not all fields are always included. Refer to the Payload properties table to understand when a field appears.

Webhook payload example (expansion enabled)

When a order.approval.pending event is triggered, the webhook sends the following JSON payload:

{
  "order": "aBCDE12fGH3iJkL4mNOpq",
  "id": "aBCDE12fGH3iJkL4mNOpq",
  "reference": "ABC123456-7891-01112",
  "buyerReference": null,
  "ipAddress": "000.000.00.000",
  "completed": false,
  "changed": 1751898991060,
  "changedValue": 1751898991060,
  "changedInSeconds": 1751898991,
  "changedDisplay": "7/7/25",
  "changedDisplayISO8601": "2025-07-07",
  "changedDisplayEmailEnhancements": "Jul 07, 2025",
  "changedDisplayEmailEnhancementsWithTime": "Jul 07, 2025 02:36:31 PM",
  "language": "en",
  "live": false,
  "currency": "USD",
  "payoutCurrency": "USD",
  "quote": "QUW6Z4TYTPOJDRTF5DJ7E2CVYAWA",
  "invoiceUrl": "https://company.onfastspring.com/account/order/null/invoice",
  "siteId": "LDN5SX4KBZCI2",
  "acquisitionTransactionType": "INVOICE_PAYMENT_ORDER",
  "account": {
    "id": "abCdE1FGH2Hij3KLMnOpqR",
    "account": "abCdE1FGH2Hij3KLMnOpqR",
    "contact": {
      "first": "Jane",
      "last": "Doe",
      "email": "[email protected]",
      "company": "ABC Company",
      "phone": "5555555555",
      "subscribed": true
    },
    "address": {
      "address line 1": "801 Garden St",
      "address line 2": "Suite 201",
      "city": "Santa Barbara",
      "country": "US",
      "postal code": "93101",
      "region": "US-CA",
      "region custom": null,
      "company": "ABC Company"
    },
    "language": "en",
    "country": "US",
    "lookup": { "global": "8x3FKfUESieeIgGoxHBRLg" },
    "url": "https://company.onfastspring.com/account"
  },
  "total": 60.0,
  "totalDisplay": "$60.00",
  "totalInPayoutCurrency": 60.0,
  "totalInPayoutCurrencyDisplay": "$60.00",
  "tax": 0.0,
  "taxDisplay": "$0.00",
  "taxInPayoutCurrency": 0.0,
  "taxInPayoutCurrencyDisplay": "$0.00",
  "subtotal": 60.0,
  "subtotalDisplay": "$60.00",
  "subtotalInPayoutCurrency": 60.0,
  "subtotalInPayoutCurrencyDisplay": "$60.00",
  "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": "Jane",
    "last": "Doe",
    "email": "[email protected]",
    "company": "ABC Company",
    "phone": "5555555555",
    "subscribed": true
  },
  "address": {
    "addressLine1": "801 Garden St",
    "addressLine2": "Suite 201",
    "city": "Santa Barbara",
    "regionCode": "CA",
    "regionDisplay": "California",
    "region": "California",
    "postalCode": "93101",
    "country": "US",
    "display": "801 Garden St, Suite 201, Santa Barbara, California, 93101, US"
  },
  "recipients": [
    {
      "recipient": {
        "first": "John",
        "last": "Doe",
        "email": "[email protected]",
        "company": "ABC Company",
        "phone": "5555555555",
        "subscribed": true,
        "account": {
          "id": "abCdE1FGH2Hij3KLMnOpqR",
          "account": "abCdE1FGH2Hij3KLMnOpqR",
          "contact": {
            "first": "John",
            "last": "Doe",
            "email": "[email protected]",
            "company": "ABC Company",
            "phone": "5555555555",
            "subscribed": true
          },
          "address": {
            "address line 1": "801 Garden St",
            "address line 2": "Suite 201",
            "city": "Santa Barbara",
            "country": "US",
            "postal code": "93101",
            "region": "US-CA",
            "region custom": null,
            "company": "ABC Company"
          },
          "language": "en",
          "country": "US",
          "lookup": { "global": "8x3FKfUESieeIgGoxHBRLg" },
          "url": "https://company.onfastspring.com/account"
         }
      }
    }
  ],
  "notes": [],
  "items": [
    {
      "product": "cloud-storage",
      "quantity": 1,
      "display": "Cloud Storage Service",
      "sku": "SKU-CS-101",
      "imageUrl": null,
      "shortDisplay": "Cloud Storage Service",
      "subtotal": 60.0,
      "subtotalDisplay": "$60.00",
      "subtotalInPayoutCurrency": 60.0,
      "subtotalInPayoutCurrencyDisplay": "$60.00",
      "discount": 0.0,
      "discountDisplay": "$0.00",
      "discountInPayoutCurrency": 0.0,
      "discountInPayoutCurrencyDisplay": "$0.00",
      "fulfillments": {},
      "withholdings": { "taxWithholdings": false },
      "proratedItemChangeAmount": 0.0,
      "proratedItemChangeAmountDisplay": "$0.00",
      "proratedItemChangeAmountInPayoutCurrency": 0.0,
      "proratedItemChangeAmountInPayoutCurrencyDisplay": "$0.00",
      "proratedItemProratedCharge": 0.0,
      "proratedItemProratedChargeDisplay": "$0.00",
      "proratedItemProratedChargeInPayoutCurrency": 0.0,
      "proratedItemProratedChargeInPayoutCurrencyDisplay": "$0.00",
      "proratedItemCreditAmount": 0.0,
      "proratedItemCreditAmountDisplay": "$0.00",
      "proratedItemCreditAmountInPayoutCurrency": 0.0,
      "proratedItemCreditAmountInPayoutCurrencyDisplay": "$0.00",
      "proratedItemTaxAmount": 0.0,
      "proratedItemTaxAmountDisplay": "$0.00",
      "proratedItemTaxAmountInPayoutCurrency": 0.0,
      "proratedItemTaxAmountInPayoutCurrencyDisplay": "$0.00",
      "proratedItemTotal": 0.0,
      "proratedItemTotalDisplay": "$0.00",
      "proratedItemTotalInPayoutCurrency": 0.0,
      "proratedItemTotalInPayoutCurrencyDisplay": "$0.00"
    }
  ]
}

Payload properties

The payload properties table outlines each property in the order.approval.pending event JSON payload, specifying their name, data type, and description.

Name Type Description
Order Details Back to top ↑
order string Unique ID of the order.
id string Duplicate of order.order.
reference string Customer-facing order reference.
buyerReference string Optional buyer-provided purchase order number.
ipAddress string IP address of the customer at purchase time.
completed boolean true if the order was completed successfully; otherwise false.
Timestamps Back to top ↑
changed integer Timestamp (in milliseconds) of the last order update.
changedValue integer Duplicate of order.changed for backward compatibility.
changedInSeconds integer Timestamp (in seconds) of the last order update.
changedDisplay string Formatted display string for the last order update.
changedDisplayISO8601 string ISO 8601 formatted timestamp for the last order update.
changedDisplayEmailEnhancements string Email-enhanced display for the last order update.
changedDisplayEmailEnhancementsWithTime string Email-enhanced display with time for the last order update.
Order Settings Back to top ↑
language string 2-letter ISO code for the order’s language.
live boolean true if the order was processed in live mode; otherwise false.
currency string 3-letter ISO currency code used for the order.
payoutCurrency string 3-letter ISO currency code for payouts.
quote string Associated quote ID, if the order was created from a quote.
invoiceUrl string URL to the customer’s downloadable invoice.
siteId string ID of the site where the order was placed.
acquisitionTransactionType string Type of acquisition transaction.
Account Object Back to top ↑
id string Unique ID for the customer account.
account string Duplicate of account.id for backward compatibility.
contact object Contact details for the account.
contact.first string First name of the account contact.
contact.last string Last name of the account contact.
contact.email string Email address of the account contact.
contact.company string Company name of the account contact, if provided.
contact.phone string Phone number of the account contact, if provided.
contact.subscribed boolean true if the account contact is subscribed to marketing emails; otherwise false.
address object Address details for the account.
address.address line 1 string Primary street address line.
address.address line 2 string Secondary street address line.
address.city string City of the account address.
address.country string 2-letter ISO country code for the address.
address.postal code string Postal or ZIP code of the address.
address.region string Region (state/province) for the address.
address.region custom string Custom region name, if not standard.
address.company string Company name associated with this address, if provided.
language string 2-letter ISO code of the account’s preferred language.
country string 2-letter ISO country code of the account’s location.
lookup object Lookup identifiers for the account.
lookup.global string Public account ID used in customer-facing portals.
url string URL to the account management page.
Pricing Back to top ↑
total number Total amount charged for the order in the transaction currency.
totalDisplay string Formatted version of order.total. Example: $8.53.
totalInPayoutCurrency number Total order amount in your disbursement currency.
totalInPayoutCurrencyDisplay string Formatted version of order.totalInPayoutCurrency.
tax number Tax amount applied to the order.
taxDisplay string Formatted version of order.tax.
taxInPayoutCurrency number Tax amount in your disbursement currency.
taxInPayoutCurrencyDisplay string Formatted version of order.taxInPayoutCurrency.
subtotal number Order subtotal before tax and discounts.
subtotalDisplay string Formatted version of order.subtotal.
subtotalInPayoutCurrency number Subtotal in your disbursement currency.
subtotalInPayoutCurrencyDisplay string Formatted version of order.subtotalInPayoutCurrency.
Discount Details Back to top ↑
discount number Total discount applied to the order in transaction currency.
discountDisplay string Formatted display of order.discount.
discountInPayoutCurrency number Discount amount in payout currency.
discountInPayoutCurrencyDisplay string Formatted display of order.discountInPayoutCurrency.
discountWithTax number Total discount including tax in transaction currency.
discountWithTaxDisplay string Formatted display of order.discountWithTax.
discountWithTaxInPayoutCurrency number Discount including tax in payout currency.
discountWithTaxInPayoutCurrencyDisplay string Formatted display of order.discountWithTaxInPayoutCurrency.
Payment Method Back to top ↑
billDescriptor string Text that appears on the customer's credit card or bank statement.
payment.type string Payment method used for the order. Example values: paypal, amazon, applepay, creditcard, kakaopay, test, bank, alipay, purchase-order, free, upi.
payment.variant string Returned when payment.type is upi. Indicates the customer's UPI app or flow. Example values: upigpay, upiphonepe, upipaytm, upidesktop.
payment.creditcard string Returned when order.payment.type is creditcard. Type of credit or debit card used. Example values: visa, mastercard, amex, discover, jcb, carteblanche, dinersclub, unionpay, elo, hipercard.
payment.cardEnding string Returned when order.payment.type is creditcard. Last four digits of the card number used for the order.
payment.bank string Returned when order.payment.type is bank. Type of bank transfer used to pay for the order. Example values: wire, brazilwire, ideal, giropay, sofort, ecard, sepa, alipay.
Customer Object Back to top ↑
customer object Details of the customer who placed the order.
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, if provided.
customer.phone string Customer’s phone number, if provided.
customer.subscribed boolean true if the customer is subscribed to marketing emails; otherwise false.
Address Object Back to top ↑
address object Billing address provided by the customer.
address.city string City of the billing address.
address.regionCode string 2-letter ISO region (state/province) code.
address.regionDisplay string Formatted display name of the region.
address.region string Region (state/province) name.
address.postalCode string Postal or ZIP code of the billing address.
address.country string 2-letter ISO country code.
address.display string Formatted display string for the full address.
Recipients Array Back to top ↑
recipients array Array of recipient objects for gifts or alternate delivery contacts.
recipients.recipient object Defines each recipient in the order.recipients array.
recipient.first string Recipient’s first name.
recipient.last string Recipient’s last name.
recipient.email string Recipient’s email address.
recipient.company string Recipient’s company name, if provided.
recipient.phone string Recipient’s phone number, if provided.
recipient.subscribed boolean true if the recipient is subscribed to marketing emails; otherwise false.
recipient.account object Duplicate of id. Included for backward compatibility.
recipient.account.id string Unique ID for the recipient's account. Generated by FastSpring.
recipient.account.account string Duplicate of .recipient.account.id.
recipient.account.contact.first string First name on the recipient’s account.
recipient.account.contact.last string Last name on the recipient’s account.
recipient.account.contact.email string Email address associated with the recipient’s account.
recipient.account.contact.company string Company name associated with the recipient’s account, if provided.
recipient.account.contact.phone string Phone number on the recipient’s account, if provided.
recipient.account.contact.subscribed boolean true if the recipient is subscribed to updates; otherwise false.
recipient.account.address object Defines the address for each recipient.
recipient.account.address.address line 1 string Recipient’s primary street address line.
recipient.account.address.address line 2 string Recipient’s secondary street address line.
recipient.account.address.city string Recipient’s city.
recipient.account.address.country string 2-letter ISO country code for the recipient.
recipient.account.address.postalCode string Recipient’s postal or ZIP code.
recipient.account.address.region string Region name (may duplicate regionDisplay).
recipient.account.address.company string Company name associated with this recipient address, if provided.
recipient.account.language string 2-letter ISO code representing the recipient's preferred language. Example: en.
recipient.account.country string 2-letter ISO country code. Example: US.
recipient.account.lookup.global string Public account ID for use in customer-facing portals.
recipient.account.url string URL to the recipient’s account management page.
Notes Back to top ↑
Note: The order notes array contains internal comments about the order. These are typically added through the FastSpring App or API and are not customer-facing.
notes array Array of internal note objects associated with the order. May be empty.
Items Array Back to top ↑
items array Array of item objects purchased in the order. Each object contains product, pricing, and subscription info.
product string ID of the product associated with the item.
quantity number Quantity of the product purchased.
display string Customer-facing name of the product.
sku string Product SKU assigned in your FastSpring catalog.
subtotal number Pre-tax subtotal for the item, in the transaction currency.
subtotalDisplay string Formatted subtotal for the item, in the transaction currency.
subtotalInPayoutCurrency number Subtotal for the item, in your payout currency.
subtotalInPayoutCurrencyDisplay string Formatted subtotal for the item, in your payout currency.
attributes object Product-level attributes applied to this item. These values are defined in your catalog or passed via API.
discount number Total discount amount applied to the item, in the transaction currency.
discountDisplay string Formatted discount amount, in the transaction currency.
discountInPayoutCurrency number Discount amount, in your payout currency.
discountInPayoutCurrencyDisplay string Formatted discount amount, in your payout currency.
Fulfillments Object Back to top ↑
fulfillments.display string Display name of the downloadable file or fulfillment action.
fulfillments.size integer File size in bytes. Applies when the fulfillment type is file.
fulfillments.file string Secure URL for downloading the fulfillment file.
fulfillments.type string Fulfillment type. Example values: file, license.
Withholdings Object Back to top ↑
withholdings.amount number Total amount withheld from this item, in the transaction currency.
withholdings.amountDisplay string Formatted display of the withheld amount. Example: $12.00.
withholdings.amountInPayoutCurrency number Amount withheld in your payout currency.
withholdings.amountInPayoutCurrencyDisplay string Formatted withheld amount in payout currency. Example: $12.00.
withholdings.percentage number Percentage of the item's total that was withheld. Example: 15.
withholdings.taxWithholdings boolean Indicates whether this withholding is related to taxes. true if tax-related; otherwise false.
Proration Details Back to top ↑
proratedItemChangeAmount number Net change in the item’s amount due to plan change and proration, in transaction currency.
proratedItemChangeAmountDisplay string Formatted display of proratedItemChangeAmount (e.g. $0.00).
proratedItemChangeAmountInPayoutCurrency number Net change amount converted to your payout currency.
proratedItemChangeAmountInPayoutCurrencyDisplay string Formatted display of proratedItemChangeAmountInPayoutCurrency.
proratedItemProratedCharge number Charge amount for the prorated portion of the new item, in transaction currency.
proratedItemProratedChargeDisplay string Formatted display of proratedItemProratedCharge.
proratedItemProratedChargeInPayoutCurrency number Prorated charge converted to your payout currency.
proratedItemProratedChargeInPayoutCurrencyDisplay string Formatted display of proratedItemProratedChargeInPayoutCurrency.
proratedItemCreditAmount number Credit amount issued for the unused portion of the previous item, in transaction currency.
proratedItemCreditAmountDisplay string Formatted display of proratedItemCreditAmount.
proratedItemCreditAmountInPayoutCurrency number Credit amount converted to your payout currency.
proratedItemCreditAmountInPayoutCurrencyDisplay string Formatted display of proratedItemCreditAmountInPayoutCurrency.
proratedItemTaxAmount number Tax applied to the prorated item adjustment, in transaction currency.
proratedItemTaxAmountDisplay string Formatted display of proratedItemTaxAmount.
proratedItemTaxAmountInPayoutCurrency number Tax amount converted to your payout currency.
proratedItemTaxAmountInPayoutCurrencyDisplay string Formatted display of proratedItemTaxAmountInPayoutCurrency.
proratedItemTotal number Total prorated adjustment (charges minus credits plus tax) for the item, in transaction currency.
proratedItemTotalDisplay string Formatted display of proratedItemTotal.
proratedItemTotalInPayoutCurrency number Total prorated adjustment converted to your payout currency.
proratedItemTotalInPayoutCurrencyDisplay string Formatted display of proratedItemTotalInPayoutCurrency.
Back to top ↑