About the Receipt Presets API

Receipt presets are customizable receipt configurations that Wix users can use to adjust the information, design, and branding of their receipts to align with their business needs.

The Receipt Presets API enables you to:

Manage a site's receipt configurations, including which business, customer and custom details to display.
Define whether to display line item descriptions and taxes charged.

Default receipt preset

Each site supports multiple receipt presets. One preset should be designated as the default, which will automatically apply whenever receipts are created without specifying a particular preset.

Use cases

Customize receipts to comply with local requirements

Before you begin

Receipt layouts can't be managed with this API. Receipt layouts can only be managed from the site dashboard under Settings > Receipt Settings.

Terminology

Receipt: A static document that serves as proof of payment for a completed transaction.
Receipt preset: A collection of receipt configurations defining the receipt's appearance, behavior, and custom fields. Presets can be used for different business scenarios, for example, multiple locations or domains within the same business.

Did this help?

Sample Use Cases and Flows

This article shares some possible use cases you could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your implementation.

Customize receipts with specific business and tax details to comply with local requirements

You can enable Wix users to customize the details of generated receipts with the Receipt Presets API.

Call Get Default Receipt Preset to retrieve the default receipt preset.
Collect the Wix user's desired changes to the receipt preset.
Call Update Receipt Preset with the desired changes. All receipts created using this preset will include the desired changes.

Did this help?

Receipt Preset Object

A Receipt preset is a set of customizable receipt configurations that control the information, design, and branding of receipts to align with a site's business needs.

Properties

idstringRead-onlyformat GUID

Receipt preset ID.

revisionstringRead-onlyformat int64

Revision number, which increments by 1 each time the receipt preset is updated. To prevent conflicting changes, the current revision must be passed when updating the receipt preset.

createdDatestringRead-onlyformat date-time

Date and time the receipt preset was created.

updatedDatestringRead-onlyformat date-time

Date and time the receipt preset was last updated.

namestringmaxLength 100

Receipt preset name.

displaySettingsDisplaySettings

Display settings.

customFieldsCustomFields

Custom fields. Values appear on the receipt in the specified order.

defaultbooleanRead-only

Whether this is the default receipt preset. The default preset is used during receipt creation when a preset isn't specified or doesn't exist.

displayValuesDisplayValues

Display values.

extendedFieldsExtendedFields

Custom field data for the receipt preset.

Extended fields must be configured in the app dashboard before they can be accessed with API calls.

Did this help?

GET

List Receipt Presets

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Lists all available receipt presets.

By default the returned receipt presets are sorted by default and updatedDate in descending order.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions

Learn more about app permissions.

Endpoint

GET

https://www.wixapis.com/receipts/v1/receipt-presets

Request

This endpoint does not take any parameters.

Response Object

receiptPresetsArray <ReceiptPreset>

List of receipt presets.

Example shown:List Receipt Presets

Retrieves a list of Receipt Presets

Request

cURL


curl -X GET \
  'https://www.wixapis.com/receipts/v1/receipt-presets' \
  -H 'Authorization: <AUTH>' \
  -H 'Content-Type: application/json' \

Response

JSON


{
  "receiptPresets": [
    {
      "id": "8046df3c-7575-4098-a5ab-c91ad8f33c47",
      "revision": 1,
      "createdDate": "2024-10-30T17:22:10.299Z",
      "updatedDate": "2024-10-30T17:22:10.299Z",
      "name": "Invoice preset",
      "templateSettingsId": "4fd78c54-b722-4300-ac62-ea71ceaec00f",
      "displayValues": {
        "titleOverride": "INV-Receipt"
      },
      "displaySettings": {
        "businessDisplayOptions": {
          "showBusinessEmail": true,
          "showBusinessPhoneNumber": true,
          "showBusinessAddress": true
        },
        "customerDisplayOptions": {
          "showCustomerEmail": true,
          "showCustomerPhoneNumber": true,
          "showCustomerShippingAddress": true,
          "showCustomerBillingAddress": true,
          "showCustomerVatId": true
        },
        "itemsDisplayOptions": {
          "showItemsDescription": true,
          "showTax": true
        },
        "totalsDisplayOptions": {
          "showTaxBreakdown": true,
          "showItemSubtotalPerTaxBreakdown": true
        }
      },
      "customFields": {
        "headerCustomFields": [
          {
            "title": "Source",
            "value": "Invoices"
          }
        ],
        "businessCustomFields": [
          {
            "title": "Business ID",
            "value": "12345"
          }
        ],
        "customerCustomFields": [
          {
            "title": "Customer Type",
            "value": "Invoice Customer"
          }
        ],
        "footerCustomFields": [
          {
            "title": "Terms",
            "value": "This receipt align to the requirements of an example."
          }
        ]
      },
      "default": false
    },
    {
      "id": "68d9d9bd-3024-4544-aa50-bf398f6a9c93",
      "revision": 1,
      "createdDate": "2024-11-03T17:22:10.299Z",
      "updatedDate": "2024-11-03T17:22:10.299Z",
      "name": "Default Orders preset",
      "templateSettingsId": "34b8928a-02c4-4ce4-a9f6-87373baabc80",
      "displaySettings": {
        "businessDisplayOptions": {
          "showBusinessEmail": true,
          "showBusinessPhoneNumber": true,
          "showBusinessAddress": true
        },
        "customerDisplayOptions": {
          "showCustomerEmail": true,
          "showCustomerPhoneNumber": true,
          "showCustomerShippingAddress": true,
          "showCustomerBillingAddress": true,
          "showCustomerVatId": true
        },
        "itemsDisplayOptions": {
          "showItemsDescription": true,
          "showTax": true
        },
        "totalsDisplayOptions": {
          "showTaxBreakdown": true,
          "showItemSubtotalPerTaxBreakdown": true
        }
      },
      "customFields": {
        "headerCustomFields": [
          {
            "title": "Source",
            "value": "Orders"
          }
        ],
        "businessCustomFields": [
          {
            "title": "Business ID",
            "value": "12345"
          }
        ],
        "customerCustomFields": [
          {
            "title": "Customer Type",
            "value": "Invoice Customer"
          }
        ],
        "footerCustomFields": [
          {
            "title": "Terms",
            "value": "This receipt align to the requirements of an example."
          }
        ]
      },
      "default": true
    }
  ]
}

Errors

400Invalid Argument

There is 1 error with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

POST

Create Receipt Preset

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates a receipt preset.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions

Learn more about app permissions.

Endpoint

POST

https://www.wixapis.com/receipts/v1/receipt-presets

Body Params

receiptPresetReceiptPresetRequired

Receipt preset to create.

Response Object

receiptPresetReceiptPreset

Created receipt preset.

Example shown:Create Receipt Preset

Creates a Receipt Preset

Request

cURL


curl -X POST \
  'https://www.wixapis.com/receipts/v1/receipt-presets' \
  -H 'Authorization: <AUTH>' \
  -H 'Content-Type: application/json' \
  -d '{
    "receiptPreset": {
      "name": "Invoice preset",
      "templateSettingsId": "4fd78c54-b722-4300-ac62-ea71ceaec00f",
      "displayValue": {
        "titleOverride": "INV-Receipt"
      },
      "displaySettings": {
        "businessDisplayOptions": {
          "showBusinessEmail": true,
          "showBusinessPhoneNumber": true,
          "showBusinessAddress": true
        },
        "customerDisplayOptions": {
          "showCustomerEmail": true,
          "showCustomerPhoneNumber": true,
          "showCustomerShippingAddress": true,
          "showCustomerBillingAddress": true,
          "showCustomerVatId": true
        },
        "itemsDisplayOptions": {
          "showItemsDescription": true,
          "showTax": true
        },
        "totalsDisplayOptions": {
          "showTaxBreakdown": true,
          "showItemSubtotalPerTaxBreakdown": true
        }
      },
      "customFields": {
        "headerCustomFields": [
          {
            "title": "Source",
            "value": "Invoices"
          }
        ],
        "businessCustomFields": [
          {
            "title": "Business ID",
            "value": "12345"
          }
        ],
        "customerCustomFields": [
          {
            "title": "Customer Type",
            "value": "Invoice Customer"
          }
        ],
        "footerCustomFields": [
          {
            "title": "Terms",
            "value": "This receipt align to the requirements of an example."
          }
        ]
      }
    }
  }'

Response

JSON


{
  "receiptPreset": {
    "id": "8046df3c-7575-4098-a5ab-c91ad8f33c47",
    "revision": 1,
    "createdDate": "2024-10-30T17:22:10.299Z",
    "updatedDate": "2024-10-30T17:22:10.299Z",
    "name": "Invoice preset",
    "templateSettingsId": "4fd78c54-b722-4300-ac62-ea71ceaec00f",
    "displayValues": {
      "titleOverride": "INV-Receipt"
    },
    "displaySettings": {
      "businessDisplayOptions": {
        "showBusinessEmail": true,
        "showBusinessPhoneNumber": true,
        "showBusinessAddress": true
      },
      "customerDisplayOptions": {
        "showCustomerEmail": true,
        "showCustomerPhoneNumber": true,
        "showCustomerShippingAddress": true,
        "showCustomerBillingAddress": true,
        "showCustomerVatId": true
      },
      "itemsDisplayOptions": {
        "showItemsDescription": true,
        "showTax": true
      },
      "totalsDisplayOptions": {
        "showTaxBreakdown": true,
        "showItemSubtotalPerTaxBreakdown": true
      }
    },
    "customFields": {
      "headerCustomFields": [
        {
          "title": "Source",
          "value": "Invoices"
        }
      ],
      "businessCustomFields": [
        {
          "title": "Business ID",
          "value": "12345"
        }
      ],
      "customerCustomFields": [
        {
          "title": "Customer Type",
          "value": "Invoice Customer"
        }
      ],
      "footerCustomFields": [
        {
          "title": "Terms",
          "value": "This receipt align to the requirements of an example."
        }
      ]
    },
    "default": false
  }
}

Errors

400Invalid Argument

There is 1 error with this status code.

500Internal

There is 1 error with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Event TriggersThis method triggers the following events:

Receipt Preset Created

Did this help?

GET

Get Receipt Preset

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a receipt preset.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions

Learn more about app permissions.

Endpoint

GET

https://www.wixapis.com/receipts/v1/receipt-presets/{receiptPresetId}

Path Params

receiptPresetIdstringRequired

Receipt preset ID to retrieve.

Response Object

receiptPresetReceiptPreset

Requested receipt preset.

Example shown:Get Receipt Preset

Retrieves a Receipt Preset

Request

cURL


curl -X GET \
  'https://www.wixapis.com/receipts/v1/receipt-presets/4fd78c54-b722-4300-ac62-ea71ceaec00f' \
  -H 'Authorization: <AUTH>' \
  -H 'Content-Type: application/json' \

Response

JSON


{
  "receiptPreset": {
    "id": "8046df3c-7575-4098-a5ab-c91ad8f33c47",
    "revision": 1,
    "createdDate": "2024-10-30T17:22:10.299Z",
    "updatedDate": "2024-10-30T17:22:10.299Z",
    "name": "Invoice preset",
    "templateSettingsId": "4fd78c54-b722-4300-ac62-ea71ceaec00f",
    "displayValues": {
      "titleOverride": "INV-Receipt"
    },
    "displaySettings": {
      "businessDisplayOptions": {
        "showBusinessEmail": true,
        "showBusinessPhoneNumber": true,
        "showBusinessAddress": true
      },
      "customerDisplayOptions": {
        "showCustomerEmail": true,
        "showCustomerPhoneNumber": true,
        "showCustomerShippingAddress": true,
        "showCustomerBillingAddress": true,
        "showCustomerVatId": true
      },
      "itemsDisplayOptions": {
        "showItemsDescription": true,
        "showTax": true
      },
      "totalsDisplayOptions": {
        "showTaxBreakdown": true,
        "showItemSubtotalPerTaxBreakdown": true
      }
    },
    "customFields": {
      "headerCustomFields": [
        {
          "title": "Source",
          "value": "Invoices"
        }
      ],
      "businessCustomFields": [
        {
          "title": "Business ID",
          "value": "12345"
        }
      ],
      "customerCustomFields": [
        {
          "title": "Customer Type",
          "value": "Invoice Customer"
        }
      ],
      "footerCustomFields": [
        {
          "title": "Terms",
          "value": "This receipt align to the requirements of an example."
        }
      ]
    },
    "default": false
  }
}

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?