The DPP Invoice Experience API publishes eleven operations for merchant invoicing — create a draft, modify invoice details, modify invoice status, retrieve, search, share, clone and download an invoice, plus create, read and modify the merchant's invoice configuration. Invoices carry the same customerId and paymentId identifier space as the Gateway Experience API.
openapi: 3.1.0
info:
title: DPP Invoice Experience API
version: '1'
description: The DPP Invoice Experience API enables merchants to manage invoice lifecycles and configurations efficiently.
It provides endpoints for creating, updating, sharing, cloning, searching, downloading, and configuring invoices. Each
operation is designed to ensure accuracy, consistency, and ease of integration. The API supports flexible routing through
baseUri parameters, ensuring compatibility with current and future structures. By offering features like invoice branding,
payment terms, health checks, Base64-encoded downloads, and secure sharing, it helps merchants streamline workflows and
enhance customer experiences. This API is particularly useful for businesses looking to standardize invoicing practices,
improve customer communication, and maintain professional and reliable financial records.
x-provenance:
method: derived
derived_from: RAML 1.0 published by Deluxe at https://developer.deluxe.com/api-ref/api/merchant-services/
derived_on: '2026-08-13'
note: Faithful mechanical conversion of the provider-published RAML 1.0 definition and its rendered request/response parameter
and example documents. No operation, field, schema or example in this file was authored by API Evangelist.
servers:
- url: https://api.deluxe.com/dpp/v1
description: Production (default routing path)
- url: https://api.deluxe.com/dpp/v1/gateway
description: Production (legacy routing path)
- url: https://sandbox.api.deluxe.com/dpp/v1
description: Sandbox / test environment
security:
- bearerAuth: []
tags:
- name: invoices
paths:
/invoices:
post:
operationId: createDraftInvoice
summary: Create Draft Invoice
tags:
- invoices
description: 'Creates draft invoice using customer details, billing information, and optional shipping data. Line items
such as sale item name, price, and quantity are required along with payment terms like due days or discounts. Draft
invoices allow merchants to review and edit before publishing, ensuring accuracy. This endpoint is the first step
in generating a professional, standardized invoice aligned with predefined invoice configurations.
> **Note:** An active invoice configuration is required before you can start creating invoices.'
parameters:
- name: partnerToken
in: header
required: true
schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
examples:
- 80ae9a4a-5efd-412e-89b9-532f2ab2f817
description: Unique Merchant Identifier for API Calls
example: 80ae9a4a-5efd-412e-89b9-532f2ab2f817
- name: requestId
in: header
required: false
schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
examples:
- 56ae9a4a-5efd-412e-89b9-532f2ab2f275
description: 'Unique request identifier in GUID format included in the header, used to trace and correlate API calls
across systems.
> **Note:** We strongly recommend including the `requestId` header in every API request. This unique GUID helps
trace and correlate API calls across systems, ensuring better observability and troubleshooting.'
example: 56ae9a4a-5efd-412e-89b9-532f2ab2f275
requestBody:
required: true
content:
application/json:
schema:
description: Object to hold of all the invoice related properties such as customerId, orderId, billingAddress,
shippingAddress, if any. You can also specify Sale items, payment terms, custom data and discount rates.
type: object
properties:
customerId:
description: CustomerId of the existing customer for whom the invoice will be issued. A new customerId will
be generated by system if not provided.
type: integer
minimum: 1
examples:
- 515365
orderId:
description: A custom identifier that a merchant can use to track the invoice against this orderId.
type: integer
minimum: 1
examples:
- 12312345
billingAddress:
description: Object to hold customer billing address details like name, address, communication details.
These details will be used to create an invoice.
type: object
properties:
firstName:
description: First Name
type: string
minLength: 1
maxLength: 100
examples:
- Alan
lastName:
description: Last Name
type: string
minLength: 1
maxLength: 100
examples:
- David
address:
description: Address line 1
type: string
minLength: 1
maxLength: 250
examples:
- 123 Main St
address2:
description: Address line 2
type: string
minLength: 1
examples:
- Apt 5
city:
description: City Name
type: string
minLength: 1
maxLength: 50
examples:
- San Francisco
state:
description: State Name
type: string
minLength: 1
maxLength: 25
examples:
- CA
country:
description: Country Name
type: string
minLength: 1
maxLength: 25
examples:
- US
postalCode:
description: Postal/Zip Code
type: string
pattern: ^\d{5}(-\d{4})?$|^[A-Z]\d[A-Z] \d[A-Z]\d$
maxLength: 10
examples:
- '94111'
phone:
description: Phone Number
type: string
pattern: ^(?:\+?\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$
examples:
- +1 123-456-7890
fax:
description: Fax Number
type: string
pattern: ^(?:\+?\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$
examples:
- +1 123-456-7890
email:
description: Email Address
type: string
pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$
maxLength: 250
examples:
- jane@email.com
website:
description: Website Name
type: string
minLength: 1
examples:
- www.deluxe.com
required:
- address
- city
- country
- email
- firstName
- lastName
- phone
- postalCode
- state
shippingAddress:
description: Object to hold customer shipping address details like name, address, communication details
along with shipping method. These details will be used to ship the sale items specified in the invoice.
type: object
properties:
shippingMethod:
description: Mode of shipping
type: string
minLength: 1
examples:
- By Air
saleItems:
description: Array to hold all the non taxable sale item(s) related details such as product Id, product
name, price, quantity etc.
type: array
items:
type: object
properties:
detailId:
description: Identifier of the sale item
type: number
minimum: 1
examples:
- 3
name:
description: Name of the sale item
type: string
minLength: 1
maxLength: 50
examples:
- Pen
price:
description: Price of the sale item
type: string
pattern: ^\d+\.\d{2}$
examples:
- '1.25'
quantity:
description: Quantity of the sale item
type: integer
minimum: 1
examples:
- 10
required:
- detailId
- name
- price
- quantity
minItems: 1
total:
description: Object to hold the total amount related fields such as discountRate and currency.
type: object
properties:
discountRate:
description: Discount rate/percentage applied on the invoice total amount. The invoice amount will be
calculated after subtracting the discount.
type: string
pattern: ^\d{1,2}\.\d{2}$
default: '0.00'
examples:
- '1.25'
currency:
description: Name of the currency that the invoice is using.
type: string
enum:
'0': USD
examples:
- USD
required:
- currency
- discountRate
paymentTerms:
description: Object to hold all payment related terms for an invoice such as dueDays.
type: object
properties:
dueDays:
description: Number of days from the invoice published date to make the payment to invoice amount.
type: integer
minimum: 1
examples:
- 2
required:
- dueDays
customData:
description: Array to hold a specific custom data model, if any. These fields can be utilized to pass any
custom data to display them in invoice
type: array
items:
type: object
properties:
name:
description: Custom Data field name or key
type: string
examples:
- Custom Data Name
value:
description: Custom Data field value
type: string
examples:
- Custom Data Value
required:
- name
- value
required:
- billingAddress
- paymentTerms
- saleItems
- total
example:
customerId: 515365
orderId: 1231245
billingAddress:
firstName: Alan
lastName: kent
address: 588 Delaware Avenue
address2: Houston
city: Bris
state: CA
country: US
postalCode: '94005'
phone: +1 123-456-7890
fax: +44-208-1234567
email: AlanKent@cmail.com
website: www.deluxe.com
shippingAddress:
firstName: Bob
lastName: murphy
address: 123 main st
address2: Houston
city: Bris
state: CA
country: US
postalCode: '94005'
phone: +1 123-456-7890
fax: +44-208-1234567
email: bobmurphy@cmail.com
website: www.deluxe.com
shippingMethod: Courier
saleItems:
- detailId: 1
name: Pen
price: '2.49'
quantity: 100
- detailId: 2
name: ball
price: '4.99'
quantity: 100
total:
discountRate: '2.50'
currency: USD
paymentTerms:
dueDays: 1
customData:
- name: message
value: Thanks for the order
- name: Custome Name
value: Custome Value
responses:
'200':
description: Successful response
content:
application/json:
schema:
description: Object to hold the new invoice response details such as invoiceId and success response message.
type: object
properties:
invoiceId:
description: Unique invoice identifier that will be generated by the system upon successful invoice creation.
type: integer
examples:
- 54321
requestId:
description: Unique identifier for the successful API call.
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
examples:
- a2406639-8692-4e1c-978d-1805eb13efdf
responseMessage:
description: Response message after creating a new invoice.
type: string
examples:
- Invoice is created successfully.
required:
- invoiceId
- requestId
- responseMessage
example:
invoiceId: 14843
responseMessage: Invoice created successfully.
requestId: a2406639-8692-4e1c-978d-1805eb13efdf
'401':
description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization
server.'
'403':
description: 'Forbidden: invalid client application credentials.'
/invoices/{invoiceId}:
put:
operationId: modifyInvoiceDetails
summary: Modify Invoice Details
tags:
- invoices
description: Updates details of an existing draft invoice using its `invoiceId`. Merchants can adjust billing, shipping,
customer information, line items, and payment terms. This ensures invoice accuracy before publishing. Useful when
customer details change or corrections are needed after initial creation.
parameters:
- name: invoiceId
in: path
required: true
schema:
type: string
description: Path parameter invoiceId.
- name: partnerToken
in: header
required: true
schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
examples:
- 80ae9a4a-5efd-412e-89b9-532f2ab2f817
description: Unique Merchant Identifier for API Calls
example: 80ae9a4a-5efd-412e-89b9-532f2ab2f817
- name: requestId
in: header
required: false
schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
examples:
- 56ae9a4a-5efd-412e-89b9-532f2ab2f275
description: 'Unique request identifier in GUID format included in the header, used to trace and correlate API calls
across systems.
> **Note:** We strongly recommend including the `requestId` header in every API request. This unique GUID helps
trace and correlate API calls across systems, ensuring better observability and troubleshooting.'
example: 56ae9a4a-5efd-412e-89b9-532f2ab2f275
requestBody:
required: true
content:
application/json:
schema:
description: Object to hold of all the invoice related properties such as customerId, orderId, billingAddress,
shippingAddress, if any. You can also specify Sale items, payment terms, custom data and discount rates.
type: object
properties:
customerId:
description: CustomerId of the existing customer for whom the invoice will be issued. A new customerId will
be generated by system if not provided.
type: integer
minimum: 1
examples:
- 515365
orderId:
description: A custom identifier that a merchant can use to track the invoice against this orderId.
type: integer
minimum: 1
examples:
- 12312345
billingAddress:
description: Object to hold customer billing address details like name, address, communication details.
These details will be used to create an invoice.
type: object
properties:
firstName:
description: First Name
type: string
minLength: 1
maxLength: 100
examples:
- Alan
lastName:
description: Last Name
type: string
minLength: 1
maxLength: 100
examples:
- David
address:
description: Address line 1
type: string
minLength: 1
maxLength: 250
examples:
- 123 Main St
address2:
description: Address line 2
type: string
minLength: 1
examples:
- Apt 5
city:
description: City Name
type: string
minLength: 1
maxLength: 50
examples:
- San Francisco
state:
description: State Name
type: string
minLength: 1
maxLength: 25
examples:
- CA
country:
description: Country Name
type: string
minLength: 1
maxLength: 25
examples:
- US
postalCode:
description: Postal/Zip Code
type: string
pattern: ^\d{5}(-\d{4})?$|^[A-Z]\d[A-Z] \d[A-Z]\d$
maxLength: 10
examples:
- '94111'
phone:
description: Phone Number
type: string
pattern: ^(?:\+?\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$
examples:
- +1 123-456-7890
fax:
description: Fax Number
type: string
pattern: ^(?:\+?\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$
examples:
- +1 123-456-7890
email:
description: Email Address
type: string
pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$
maxLength: 250
examples:
- jane@email.com
website:
description: Website Name
type: string
minLength: 1
examples:
- www.deluxe.com
required:
- address
- city
- country
- email
- firstName
- lastName
- phone
- postalCode
- state
shippingAddress:
description: Object to hold customer shipping address details like name, address, communication details
along with shipping method. These details will be used to ship the sale items specified in the invoice.
type: object
properties:
shippingMethod:
description: Mode of shipping
type: string
minLength: 1
examples:
- By Air
saleItems:
description: Array to hold all the non taxable sale item(s) related details such as product Id, product
name, price, quantity etc.
type: array
items:
type: object
properties:
detailId:
description: Identifier of the sale item
type: number
minimum: 1
examples:
- 3
name:
description: Name of the sale item
type: string
minLength: 1
maxLength: 50
examples:
- Pen
price:
description: Price of the sale item
type: string
pattern: ^\d+\.\d{2}$
examples:
- '1.25'
quantity:
description: Quantity of the sale item
type: integer
minimum: 1
examples:
- 10
required:
- detailId
- name
- price
- quantity
minItems: 1
total:
description: Object to hold the total amount related fields such as discountRate and currency.
type: object
properties:
discountRate:
description: Discount rate/percentage applied on the invoice total amount. The invoice amount will be
calculated after subtracting the discount.
type: string
pattern: ^\d{1,2}\.\d{2}$
default: '0.00'
examples:
- '1.25'
currency:
description: Name of the currency that the invoice is using.
type: string
enum:
'0': USD
examples:
- USD
required:
- currency
- discountRate
paymentTerms:
description: Object to hold all payment related terms for an invoice such as dueDays.
type: object
properties:
dueDays:
description: Number of days from the invoice published date to make the payment to invoice amount.
type: integer
minimum: 1
examples:
- 2
required:
- dueDays
customData:
description: Array to hold a specific custom data model, if any. These fields can be utilized to pass any
custom data to display them in invoice
type: array
items:
type: object
properties:
name:
description: Custom Data field name or key
type: string
examples:
- Custom Data Name
value:
description: Custom Data field value
type: string
examples:
- Custom Data Value
required:
- name
- value
required:
- billingAddress
- paymentTerms
- saleItems
- total
example:
invoiceNumber: '10000032'
customerId: 515365
orderId: 12312345
billingAddress:
firstName: Alan
lastName: kent
address: 588 Delaware Avenue
address2: Houston
city: Bris
state: CA
country: US
postalCode: '94005'
phone: +1 123-456-7890
fax: +44-208-1234567
email: sampath@cmail.com
website: www.deluxbill.com
shippingAddress:
firstName: Bob
lastName: murphy
address: 588 Delaware Avenue
address2: Houston
city: Bris
state: CA
country: US
postalCode: '94005'
phone: +1 123-456-7890
fax: +44-208-1234567
email: bobmurphy@cmail.com
website: www.deluxship.com
shippingMethod: Courier
saleItems:
- detailId: 1
name: Product one
price: '12.50'
quantity: 100
- detailId: 2
name: Product two
price: '3.99'
quantity: 52
total:
discountRate: '2.50'
currency: USD
paymentTerms:
dueDays: 1
customData:
- name: Invoice Number
value: inv1234
- name: Custom Name
value: Custome Value
responses:
'200':
description: Successful response
content:
application/json:
schema:
description: Object to hold the modified invoice response details such as invoiceId and success response message.
type: object
properties:
invoiceId:
description: Unique identifier for the invoice.
type: integer
examples:
- 54321
requestId:
description: Unique identifier for the successful API call.
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
examples:
- a2406639-8692-4e1c-978d-1805eb13efdf
responseMessage:
description: Response message after modifying an existing draft invoice.
type: string
examples:
- Invoice is updated successfully.
required:
- invoiceId
- requestId
- responseMessage
example:
invoiceId: 14843
responseMessage: Invoice updated successfully.
requestId: a2406639-8692-4e1c-978d-1805eb13efdf
'401':
description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization
server.'
'403':
description: 'Forbidden: invalid client application credentials.'
patch:
operationId: modifyInvoiceStatus
summary: Modify Invoice Status
tags:
- invoices
description: Allows merchants to **publish** or **cancel** a draft invoice using its `invoiceId`. Publishing makes it
visible to customers, while canceling removes drafts that are no longer valid. This helps maintain accurate records
and prevents unintended distribution of invoices.
parameters:
- name: invoiceId
in: path
required: true
schema:
type: string
description: Path parameter invoiceId.
- name: partnerToken
in: header
required: true
schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
examples:
- 80ae9a4a-5efd-412e-89b9-532f2ab2f817
description: Unique Merchant Identifier for API Calls
example: 80ae9a4a-5efd-412e-89b9-532f2ab2f817
- name: requestId
in: header
required: false
schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
examples:
- 56ae9a4a-5efd-412e-89b9-532f2ab2f275
description: 'Unique request identifier in GUID format included in the header, used to trace and correlate API calls
across systems.
> **Note:** We strongly recommend including the `requestId` header in every API request. This unique GUID helps
trace and correlate API calls across systems, ensuring better observability and troubleshooting.'
example: 56ae9a4a-5efd-412e-89b9-532f2ab2f275
requestBody:
required: true
content:
application/json:
schema:
description: Object to hold the invoice status that the invoice to be.
type: object
properties:
invoiceStatus:
description: The status to which invoice is to be modified. You can either publish/cancel any invoice other
than paid ones.
type: string
enum:
'0': PUBLISH
'1': CANCEL
examples:
- PUBLISH
required:
- invoiceStatus
example:
invoiceStatus: PUBLISH
responses:
'200':
description: Successful response
content:
application/json:
schema:
description: Object to hold the updated invoice status details such as invoiceId and success response message.
type: object
properties:
invoiceId:
descrip
# --- truncated at 32 KB (112 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/deluxe/refs/heads/main/openapi/deluxe-dpp-invoices-openapi.yml