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: description: Unique identifier for the invoice. type: integer examples: - 56379 responseMessage: description: Response message after publishing or canceling any invoice. type: string examples: - Invoice is published successfully. requestId: description: Unique identifier for the successful API call. type: string examples: - a2406639-8692-4e1c-978d-1805eb13efdf required: - invoiceId - requestId - responseMessage example: invoiceId: 4321 responseMessage: Invoice published 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.' get: operationId: getSpecificInvoice summary: Get Specific Invoice tags: - invoices description: Retrieves details of a specific invoice using its invoiceId. The response includes billing and shipping addresses, items, totals, discounts, payment terms, and current status. If payment is made, details are also included. This endpoint is key for auditing, reporting, and customer inquiries. 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 responses: '200': description: Successful response content: application/json: schema: description: Object to hold of all the invoice related details such as customerId, orderId, billingAddress, shippingAddress, Sale items, payment terms, total amount, payment details and custom data. type: object properties: invoiceId: description: Unique identifier for the invoice. type: integer examples: - 54321 invoiceNumber: description: Invoice identifier for the merchant. type: string examples: - INV000123 createdDate: description: Date of invoice creation. type: string pattern: ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4}$ examples: - 01/31/2025 invoiceStatus: description: Current status of the invoice. type: string enum: '0': DRAFT '1': PUBLISH '2': UNPAID '3': OVERDUE '4': PAID '5': CANCEL '6': DELETE examples: - PAID invoicePublishedDate: description: Published date of invoice. oneOf: - type: string pattern: ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4}$ examples: - 01/31/2025 customerId: description: CustomerID added/created in the invoice oneOf: [] orderId: description: A custom identifier that a merchant can use to track the invoice against this orderId. type: - integer - 'null' 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 - 'null' examples: - By Air required: - shippingMethod 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 invoice total amount, discount rate 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 paymentDetails: description: Array to hold the payment related details if any payment made against this invoice amount. The details includes amount paid, payment transaction date and paymentId. type: array items: type: object properties: amount: description: The amount paid in this transaction. type: string examples: - '400.50' date: description: Payment transaction date. type: string pattern: ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4}$ examples: - 01/31/2025 paymentId: description: Payment gateway transaction id. 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: - d290f1ee-6c54-4b01-90e6-d701748f0851 required: - amount - date - paymentId customData: description: Array to hold a specific custom data model, if any. These fields can be utilized 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 - createdDate - customerId - invoiceId - invoiceNumber - invoicePublishedDate - invoiceStatus - orderId - paymentTerms - saleItems - total example: invoiceId: 21599 invoiceNumber: '100000132' createdDate: 12/16/2024 invoiceStatus: DRAFT invoicePublishedDate: 12/16/2024 customerId: 515365 orderId: 1231245 billingAddress: firstName: Alan lastName: kent address: 588 Delaware Avenue address2: Houston city: Bris state: CA country: US postalCode: '94005' phone: '+11234567890' fax: '+11234567890' 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: '+14085551234' fax: '+14085551234' 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: amount: '730.30' discountRate: '2.50' currency: USD paymentTerms: dueDays: 5 dueDate: 12/21/2024 latePenaltyRate: '1.50' paymentLinkId: 6ff4e445-6aae-4c25-bc55-1348435145c2 paymentDetails: - amount: '400.00' date: 02/15/2025 paymentId: 2b5c68f9-4a11-a553-d140-daacaf559851 customData: - name: message value: Thanks for the order - name: Custome Name value: Custome Value '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /invoices/search: post: operationId: searchInvoice summary: Search Invoice tags: - invoices description: Enables merchants to find invoices using filters like date ranges, invoiceId, customerId, and status. This is useful for audits, reporting, overdue payment tracking, or quickly locating invoices during customer support inquiries. It reduces manual searches and improves operational efficiency. 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 the invoice search criteria such as due date range, invoice details, customer details and page details. type: object properties: fromDueDate: description: The start of the due date for which invoice details are to be retrieved. type: string pattern: ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4}$ examples: - 01/31/2025 toDueDate: description: The end of the due date for which invoice details are to be retrieved. type: object invoiceNumber: description: Invoice identifier for the merchant. type: string minLength: 1 examples: - INV1000234 invoiceStatus: description: Status or statuses of a particular invoice you want to search. type: array items: description: Current status of a particular invoice. type: string enum: '0': DRAFT '1': PUBLISH '2': UNPAID '3': OVERDUE '4': PAID '5': CANCEL '6': DELETE examples: - PAID minItems: 1 pageSize: description: Number of results per page type: integer minimum: 1 examples: - 5 pageNumber: description: Page number for pagination type: integer minimum: 1 examples: - 5 searchString: description: Search string that can be used to fetch the all the invoices that includes the given search string. type: string minLength: 1 examples: - narayana 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: - 12345 example: invoiceNumber: '100000163' invoiceStatus: - DRAFT pageSize: 20 pageNumber: 55 searchString: narayana fromDueDate: 01/20/2025 toDueDate: 02/20/2025 customerId: 12345 responses: '200': description: Successful response content: application/json: schema: type: array items: type: object properties: invoiceId: type: integer minimum: 1 examples: - 54321 invoiceNumber: type: string minLength: 1 examples: - INV1000234 invoiceStatus: description: Current status of a particular invoice. type: string enum: '0': DRAFT '1': PUBLISH '2': UNPAID '3': OVERDUE '4': PAID '5': CANCEL '6': DELETE examples: - PAID createdDate: description: Invoice created date type: string pattern: ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4}$ examples: - 01/31/2025 dueDate: description: Invoice payment due date type: object invoiceAmount: description: Total value of the invoice type: string examples: - '23.56' isLatePaymentFee: description: Flag to indicate if the late payment fee is enabled for the particular invoice or not. type: boolean examples: - true firstName: description: First name of the customer. type: string examples: - narayana lastName: description: Last name of the customer. type: string examples: - Konuri email: description: E-mail address of the customer type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com phone: description: Phone number of the customer type: string pattern: ^(?:\+?\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ examples: - +1 123-456-7890 required: - createdDate - dueDate - email - firstName - invoiceAmount - invoiceId - invoiceNumber - invoiceStatus - isLatePaymentFee - lastName - phone example: - invoiceId: 21951 invoiceNumber: '100000384' invoiceStatus: DRAFT createdDate: 01/31/2025 dueDate: 02/01/2025 invoiceAmount: '24.65' isLatePaymentFee: false customerId: 1347 firstName: Alan lastName: A.Leclairdgd email: test@deluxe.com phone: '6505551234' - invoiceId: 21950 invoiceNumber: '100000383' invoiceStatus: PAID createdDate: 01/31/2025 dueDate: 02/05/2025 invoiceAmount: '61.30' isLatePaymentFee: false customerId: 0 firstName: harsha lastName: bharule email: narayana@email.com phone: '6105657845' '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /invoices/share: post: operationId: shareInvoice summary: Share Invoice tags: - invoices description: Allows invoices to be shared with customers via email, SMS, or both. This ensures customers are promptly notified and can easily access their invoices. Sharing supports better communication, reduces missed payments, and enhances customer satisfaction. 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 the invoice delivery method details. This can be used to share the invoice over e-mail or SMS or both. type: object properties: invoiceId: type: integer minimum: 1 examples: - 54321 invoiceNumber: type: string minLength: 1 examples: - INV1000234 deliveryMethod: oneOf: - type: object properties: email: description: Email id to which invoice to be shared type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com phone: description: Phone number to which invoice is to be shared type: string pattern: ^(?:\+?\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ examples: - +1 123-456-7890 required: - email - type: object properties: email: description: Email id to which invoice to be shared type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com phone: description: Phone number to which invoice is to be shared type: string pattern: ^(?:\+?\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ examples: - +1 123-456-7890 required: - phone required: - deliveryMethod - invoiceId - invoiceNumber example: invoiceId: 4321 invoiceNumber: INV1000234 deliveryMethod: email: jane@email.com phone: '+918272372381' responses: '200': description: Successful response content: application/json: schema: description: Object to hold the shared invoice details and success response message. type: object properties: invoiceId: description: Unique identifier for the invoice that is shared. type: integer examples: - 56379 responseMessage: description: Response message after sharing the invoice. type: string examples: - Invoice shared successfully. requestId: description: Unique identifier for the successful API call. type: string examples: - a2406639-8692-4e1c-978d-1805eb13efdf required: - invoiceId - requestId - responseMessage example: invoiceId: 4321 responseMessage: Invoice shared 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/clone: post: operationId: cloneInvoice summary: Clone Invoice tags: - invoices description: Creates a duplicate of an existing invoice using its invoiceId. The cloned invoice includes all original details but is saved in draft status, allowing edits before publishing. This is particularly useful for recurring customers or repeat orders, reducing manual entry and errors. 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 the existing invoice details to clone the same. type: object properties: invoiceId: description: Unique identifier for the invoice. type: integer minimum: 1 examples: - 54321 required: - invoiceId example: invoiceId: 4321 responses: '200': description: Successful response content: application/json: schema: description: Object to hold the cloned invoice details such as new invoiceId and success response message. type: object properties: invoiceId: description: New invoice identifier generated after cloning the existing invoice. type: integer examples: - 56379 responseMessage: description: Response message after cloning an invoice. type: string examples: - Invoice is cloned successfully. requestId: description: Unique identifier for the successful API call. type: string examples: - a2406639-8692-4e1c-978d-1805eb13efdf required: - invoiceId - requestId - responseMessage example: invoiceId: 14843 responseMessage: Invoice is cloned 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/download/{invoiceId}: get: operationId: downloadInvoice summary: Download Invoice tags: - invoices description: Retrieves an invoice as a Base64-encoded string, which can be decoded into a PDF. This ensures customers receive professional, printable documents suitable for storage, sharing, and compliance purposes. 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 responses: '200': description: Successful response content: application/json: schema: description: Object to hold the downloaded invoice details such as invoiceId and invoiceString in base64 encoded string format. type: object properties: invoiceId: description: Unique identifier for the invoice. type: integer examples: - 56379 invoiceString: description: Invoice in base64 encoded string format. type: string examples: - JVBERi0xLjcKJeLjz9MKOCAwIG9iago8PC9BIDkgMCBSL0JvcmRlclswIDAgMF0vRiA0L1AgNCAwIFIvUmVjdFs0MjkuOCA3NjQuMTQgNTE5LjUyIDc3NS4xMl0vU3VidHlwZS9MaW5rPj4KZW5kb2JqCjEwIDAgb2JqCjw8L0EgMTEgMCBSL0JvcmRlclswIDAgMF0vRiA0L1AgNCAwIFIvUmVjdFs0MjkuOCA3NTAuNzkgNTAzLjczIDc2MS43N10vU3VidHlwZS9MaW5rPj4KZW5kb2JqCjEyIDAgb2JqCjw8L0EgMTMgMCBSL0JvcmRlclswIDAgMF0vRiA0L1AgNCAwIFIvUmVjdFs3MC40MiA2MjkuOTIgMTg4LjggNjQwLjldL1N1YnR5cGUvTGluaz4= required: - invoiceId - invoiceString example: invoiceId: 4321 invoiceString: JVBERi0xLjcKJeLjz9MKOCAwIG9iago8PC9BIDkgMCBSL0JvcmRlclswIDAgMF0vRiA0L1AgNCAwIFIvUmVjdFs0MjkuOCA3NjQuMTQgNTE5LjUyIDc3NS4xMl0vU3VidHlwZS9MaW5rPj4KZW5kb2JqCjEwIDAgb2JqCjw8L0EgMTEgMCBSL0JvcmRlclswIDAgMF0vRiA0L1AgNCAwIFIvUmVjdFs0MjkuOCA3NTAuNzkgNTAzLjczIDc2MS43N10vU3VidHlwZS9MaW5rPj4KZW5kb2JqCjEyIDAgb2JqCjw8L0EgMTMgMCBSL0JvcmRlclswIDAgMF0vRiA0L1AgNCAwIFIvUmVjdFs3MC40MiA2MjkuOTIgMTg4LjggNjQwLjldL1N1YnR5cGUvTGluaz4= '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /invoices/configuration: post: operationId: createInvoiceConfiguration summary: Create Invoice Configuration tags: - invoices description: Allows merchants to set up invoice configurations, including merchant details, branding, payment reminders, due days, colors, logos, and display options. A configuration must be created before generating invoices, ensuring standardization and professionalism across all 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 the merchant details like merchant/business name, business address including communication details. You can also specify the configurations whether these details should be visible in the invoice or not. You can also provide details related to invoice colors and business logos. type: object properties: isEnableConfiguration: description: Flag to indicate whether the invoice configuration is enabled/disabled. type: boolean examples: - false invoiceNumberStartWith: description: A user specific string that can be used as a prefix while generating an invoice number(s). This cannot be modified once you start issuing the invoice. type: string minLength: 1 maxLength: 6 examples: - '100000' autoReminderDayBeforeDueDate: description: Number of days before the due date that a customer needs to get a payment reminder. type: integer minimum: 1 examples: - 3 latePenaltyRate: description: Penalty rate/percentage that can be charged on the invoice total amount, if dueDay(s) are exceeded. type: string pattern: ^\d{1,2}\.\d{2}$ examples: - '1.25' merchantAddress: description: Object to hold the merchant details like business name, business address including communication details. 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 configurations: description: Object to hold configuration details related to merchantAddress and communication details. These details are used to determine the specific field/detail that should be visible on the invoice or not. type: object properties: isFirstNameVisible: description: Flag to indicate whether the merchant's First Name should be displayed on the invoice or not. type: boolean default: false examples: - true isLastNameVisible: description: Flag to indicate whether the merchant's Last Name should be displayed on the invoice or not. It will be always defaulted to First Name configuration. type: boolean default: false examples: - true isAddressVisible: description: Flag to indicate whether the merchant's Address should be displayed on the invoice or not. type: boolean default: false examples: - true isAddress2Visible: description: Flag to indicate whether the merchant's Address line 2 should be displayed on the invoice or not. type: boolean default: false examples: - true isCityVisible: description: Flag to indicate whether the merchant's City name should be displayed on the invoice or not. type: boolean default: false examples: - true isStateVisible: description: Flag to indicate whether the merchant's State name should be displayed on the invoice or not. type: boolean default: false examples: - true isCountryVisible: description: Flag to indicate whether the merchant's Country name should be displayed on the invoice or not. type: boolean default: false examples: - true isPostalCodeVisible: description: Flag to indicate whether the merchant's Postal Code should be displayed on the invoice or not. type: boolean default: false examples: - true isEmailVisible: description: Flag to indicate whether the merchant's emailId should be displayed on the invoice or not. type: boolean default: false examples: - true isPhoneVisible: description: Flag to indicate whether the merchant's Phone number should be displayed on the invoice or not. type: boolean default: false examples: - true isFaxVisible: description: Flag to indicate whether the merchant's Fax number should be displayed on the invoice or not. type: boolean default: false examples: - true isWebsiteVisible: description: Flag to indicate whether the merchant's website address should be displayed on the invoice or not. type: boolean default: false examples: - true required: - autoReminderDayBeforeDueDate - invoiceNumberStartWith - isEnableConfiguration - latePenaltyRate - merchantAddress example: isEnableConfiguration: true dueDays: 9 invoiceNumberStartWith: '100000' autoReminderDayBeforeDueDate: 3 latePenaltyRate: '1.25' merchantAddress: firstName: Deluxe lastName: Corporation address: 123 Main St address2: Apt 5 city: CA state: CA country: US postalCode: '50232' email: deluxecorp@email.com fax: '+9112345678901' phone: '+919632587411' website: www.deluxe.com configurations: isFirstNameVisible: true isLastNameVisible: true isAddress2Visible: true isAddressVisible: true isCityVisible: true isCountryVisible: true isEmailVisible: true isFaxVisible: true isPhoneVisible: true isPostalCodeVisible: true isStateVisible: true isWebsiteVisible: true responses: '200': description: Successful response content: application/json: schema: description: Object to hold the new invoice configuration response details such as configurationId and success response message. type: object properties: configurationId: description: Unique identifier generated after creating a new invoice configuration. type: integer examples: - 17 responseMessage: description: Response message after creating a new invoice configuration. type: string examples: - Invoice configuration created successfully 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 required: - configurationId - requestId - responseMessage example: configurationId: 41 responseMessage: invoice configuration created requestId: a2406639-8692-4e1c-978d-1805eb19efdf '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' get: operationId: getInvoiceConfiguration summary: Get Invoice Configuration tags: - invoices description: Retrieves current configuration details for a merchant, including branding preferences, reminders, and invoice enablement status. This ensures merchants can review or validate settings applied to all generated 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 responses: '200': description: Successful response content: application/json: schema: description: Object to hold the merchant details like merchant/business name, business address including communication details. You can also specify the configurations whether these details should be visible in the invoice or not. You can also provide details related to invoice colors and business logos. type: object properties: isEnableConfiguration: description: Flag to indicate whether the invoice configuration is enabled/disabled. type: boolean examples: - false invoiceNumberStartWith: description: A user specific string that can be used as a prefix while generating an invoice number(s). This cannot be modified once you start issuing the invoice. type: string minLength: 1 maxLength: 6 examples: - '100000' autoReminderDayBeforeDueDate: description: Number of days before the due date that a customer needs to get a payment reminder. type: integer minimum: 1 examples: - 3 latePenaltyRate: description: Penalty rate/percentage that can be charged on the invoice total amount, if dueDay(s) are exceeded. type: string pattern: ^\d{1,2}\.\d{2}$ examples: - '1.25' merchantAddress: description: Object to hold the merchant details like business name, business address including communication details. 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 configurations: description: Object to hold configuration details related to merchantAddress and communication details. These details are used to determine the specific field/detail that should be visible on the invoice or not. type: object properties: isFirstNameVisible: description: Flag to indicate whether the merchant's First Name should be displayed on the invoice or not. type: boolean default: false examples: - true isLastNameVisible: description: Flag to indicate whether the merchant's Last Name should be displayed on the invoice or not. It will be always defaulted to First Name configuration. type: boolean default: false examples: - true isAddressVisible: description: Flag to indicate whether the merchant's Address should be displayed on the invoice or not. type: boolean default: false examples: - true isAddress2Visible: description: Flag to indicate whether the merchant's Address line 2 should be displayed on the invoice or not. type: boolean default: false examples: - true isCityVisible: description: Flag to indicate whether the merchant's City name should be displayed on the invoice or not. type: boolean default: false examples: - true isStateVisible: description: Flag to indicate whether the merchant's State name should be displayed on the invoice or not. type: boolean default: false examples: - true isCountryVisible: description: Flag to indicate whether the merchant's Country name should be displayed on the invoice or not. type: boolean default: false examples: - true isPostalCodeVisible: description: Flag to indicate whether the merchant's Postal Code should be displayed on the invoice or not. type: boolean default: false examples: - true isEmailVisible: description: Flag to indicate whether the merchant's emailId should be displayed on the invoice or not. type: boolean default: false examples: - true isPhoneVisible: description: Flag to indicate whether the merchant's Phone number should be displayed on the invoice or not. type: boolean default: false examples: - true isFaxVisible: description: Flag to indicate whether the merchant's Fax number should be displayed on the invoice or not. type: boolean default: false examples: - true isWebsiteVisible: description: Flag to indicate whether the merchant's website address should be displayed on the invoice or not. type: boolean default: false examples: - true required: - autoReminderDayBeforeDueDate - invoiceNumberStartWith - isEnableConfiguration - latePenaltyRate - merchantAddress example: configurationId: 47 createdDate: '2024-09-13T08:14:50.063' isEnableConfiguration: true dueDays: 9 invoiceNumberStartWith: '100000' autoReminderDayBeforeDueDate: 3 latePenaltyRate: '1.25' merchantAddress: firstName: Deluxe lastName: Corporation address: 123 Main St address2: Apt 5 city: CA state: CA country: US postalCode: '50232' email: deluxecorp@email.com fax: '+9112345678901' phone: '+919632587411' website: www.deluxe.com configurations: isFirstNameVisible: true isLastNameVisible: true isAddress2Visible: true isAddressVisible: true isCityVisible: true isCountryVisible: true isEmailVisible: true isFaxVisible: true isPhoneVisible: true isPostalCodeVisible: true isStateVisible: true isWebsiteVisible: true '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /invoices/configuration/{configurationId}: put: operationId: modifyInvoiceConfiguration summary: Modify Invoice Configuration tags: - invoices description: Modify an existing configuration using configurationId. Merchants can revise merchant details, logos, colors, reminders, display preferences, and enable/disable invoice generation. This ensures configurations remain aligned with branding and policy changes. parameters: - name: configurationId in: path required: true schema: type: string description: Path parameter configurationId. - 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 merchant details like merchant/business name, business address including communication details. You can also specify the configurations whether these details should be visible in the invoice or not. You can also provide details related to invoice colors and business logos. type: object properties: isEnableConfiguration: description: Flag to indicate whether the invoice configuration is enabled/disabled. type: boolean examples: - false invoiceNumberStartWith: description: A user specific string that can be used as a prefix while generating an invoice number(s). This cannot be modified once you start issuing the invoice. type: string minLength: 1 maxLength: 6 examples: - '100000' autoReminderDayBeforeDueDate: description: Number of days before the due date that a customer needs to get a payment reminder. type: integer minimum: 1 examples: - 3 latePenaltyRate: description: Penalty rate/percentage that can be charged on the invoice total amount, if dueDay(s) are exceeded. type: string pattern: ^\d{1,2}\.\d{2}$ examples: - '1.25' merchantAddress: description: Object to hold the merchant details like business name, business address including communication details. 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 configurations: description: Object to hold configuration details related to merchantAddress and communication details. These details are used to determine the specific field/detail that should be visible on the invoice or not. type: object properties: isFirstNameVisible: description: Flag to indicate whether the merchant's First Name should be displayed on the invoice or not. type: boolean default: false examples: - true isLastNameVisible: description: Flag to indicate whether the merchant's Last Name should be displayed on the invoice or not. It will be always defaulted to First Name configuration. type: boolean default: false examples: - true isAddressVisible: description: Flag to indicate whether the merchant's Address should be displayed on the invoice or not. type: boolean default: false examples: - true isAddress2Visible: description: Flag to indicate whether the merchant's Address line 2 should be displayed on the invoice or not. type: boolean default: false examples: - true isCityVisible: description: Flag to indicate whether the merchant's City name should be displayed on the invoice or not. type: boolean default: false examples: - true isStateVisible: description: Flag to indicate whether the merchant's State name should be displayed on the invoice or not. type: boolean default: false examples: - true isCountryVisible: description: Flag to indicate whether the merchant's Country name should be displayed on the invoice or not. type: boolean default: false examples: - true isPostalCodeVisible: description: Flag to indicate whether the merchant's Postal Code should be displayed on the invoice or not. type: boolean default: false examples: - true isEmailVisible: description: Flag to indicate whether the merchant's emailId should be displayed on the invoice or not. type: boolean default: false examples: - true isPhoneVisible: description: Flag to indicate whether the merchant's Phone number should be displayed on the invoice or not. type: boolean default: false examples: - true isFaxVisible: description: Flag to indicate whether the merchant's Fax number should be displayed on the invoice or not. type: boolean default: false examples: - true isWebsiteVisible: description: Flag to indicate whether the merchant's website address should be displayed on the invoice or not. type: boolean default: false examples: - true required: - autoReminderDayBeforeDueDate - invoiceNumberStartWith - isEnableConfiguration - latePenaltyRate - merchantAddress example: isEnableConfiguration: true dueDays: 9 invoiceNumberStartWith: '100000' autoReminderDayBeforeDueDate: 3 latePenaltyRate: '1.25' merchantAddress: firstName: Deluxe lastName: Corporation address: 123 Main St address2: Apt 5 city: CA state: CA country: US postalCode: '50232' email: deluxecorp@hmail.com fax: '+9112345678901' phone: '+919632587411' website: www.deluxe.com configurations: isFirstNameVisible: true isLastNameVisible: true isAddress2Visible: true isAddressVisible: true isCityVisible: true isCountryVisible: true isEmailVisible: true isFaxVisible: true isPhoneVisible: true isPostalCodeVisible: true isStateVisible: true isWebsiteVisible: true responses: '200': description: Successful response content: application/json: schema: description: Object to hold the modified invoice configuration response details such as configurationId and success response message. type: object properties: configurationId: description: Unique identifier for the invoice configuration. type: integer examples: - 17 responseMessage: description: Response message after modifying an invoice configuration. type: string examples: - success 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 required: - configurationId - requestId - responseMessage example: configurationId: 17 responseMessage: Invoice configuration updated requestId: a2406639-8692-4e1c-978d-1805eb19efdf '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'This API supports OpenID Connect OAuth 2.0 for authenticating all API requests. Bearer tokens are obtained from the Deluxe security service token endpoint using client credentials and expire after 60 minutes.' basicAuth: type: http scheme: basic description: This API supports Anypoint's Client ID Enforcement authentication policy.