B2B Edition
B2B Edition APIs
Server to Server Management APIs
Invoice Management
Invoice

Invoice

Get invoice detail

GET /invoices/{invoiceId}

Request

get invoice detail

Authentication

  • authToken in header

Parameters

  • invoiceId in path - string
    required
    invoice id

example

curl --request GET \
--url 'https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices/[invoiceId]' \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json

  • code    number

  • data    object

    Extra Field Values
    Example: {"extraFields":[{"fieldName":"string","fieldValue":"string"}]}

  • meta    object
    required

200

{
"code": 200,
"data": {
"id": 9,
"customerId": "95075",
"externalId": "23",
"externalCustomerId": "123",
"invoiceNumber": "00000009",
"type": "Invoice on Shipment",
"dueDate": 1617675497,
"status": 1,
"orderNumber": "104",
"purchaseOrderNumber": "123",
"details": {
"type": "StandardInvoiceDetails",
"header": {
"costLines": [
{
"amount": {
"code": "USD",
"value": "349.5000"
},
"description": "Subtotal"
},
{
"amount": {
"code": "USD",
"value": "0.0000"
},

example-1

{
"code": 0,
"data": {
"id": 0,
"customerId": "string",
"externalCustomerId": "string",
"externalId": "string",
"invoiceNumber": "string",
"type": "string",
"dueDate": 0,
"status": 0,
"orderNumber": "string",
"purchaseOrderNumber": "string",
"details": {
"type": "string",
"header": {
"costLines": [
{
"amount": {
"code": "string",
"value": "string"
},
"description": "string"
}
],
"orderDate": 0,
"billingAddress": {
"city": "string",
"state": "string",
"country": "string",

Update an invoice

PUT /invoices/{invoiceId}

Request

update an invoice

Authentication

  • authToken in header

Parameters

  • invoiceId in path - string
    required
    invoice id

Body

object | application/json

  • customerId    string

    B2B Edition Company ID
    >= 1 characters

  • externalCustomerId    string

    Ext Customer ID
    >= 1 characters

  • externalId    string

    Ext Invoice ID
    >= 1 characters

  • invoiceNumber    string

    Invoice Number, must be unique
    >= 1 characters

  • type    string

    >= 1 characters

  • dueDate    number

    Invoice due date

  • status    number

    invoice status, noted status will be auto set to 2 when open balance is <= 0

  • purchaseOrderNumber    string

    PO Number
    >= 1 characters

  • details    object

    Details that will show on the invoice. When updating this field, the new value will completely replace the existing details. To preserve existing details while making updates, retrieve the current details first, and make your edits to that object before submitting the changes.

  • source    number

    Mark the source of the invoice, 0 for B2B Edition, 1 for external.

  • originalBalance    object

    Invoice original balance

  • openBalance    object

    Invoice balance awaiting for payment

  • createdAt    integer

  • externalPdfUrl    string

    The URL of an externally hosted PDF file to be associated with this invoice. The file size must not exceed 5 MB. Ensure that the file hosting service supports Cross-Origin Resource Sharing (CORS) to allow our system to access the file. To remove an existing PDF link, use an empty string.

  • extraFields    array[object]

Update body with details field

{
"customerId": "3",
"dueDate": 1619826907,
"details": {
"header": {
"costLines": [
{
"amount": {
"code": "USD",
"value": "400.0000"
},
"description": "Subtotal"
},
{
"amount": {
"code": "USD",
"value": "0.0000"
},
"description": "Freight"
},
{
"amount": {
"code": "USD",
"value": "0.0000"
},
"description": "Sales Tax"
}
]
},
"details": {
"lineItems": [
{

Update body without details field

{
"openBalance": {
"code": "USD",
"value": "12.0000"
}
}

Response

OK

Body

object | application/json

  • code    number
    required

  • data    object
    required

  • meta    object
    required

200

{
"code": 200,
"data": {
"id": 33
},
"meta": {
"message": "SUCCESS"
}
}

400

{
"code": 400,
"meta": {
"message": "Bad Requests Error",
"errors": "Please enter a valid number; "
},
"data": {
"id": 33
}
}

Delete an invoice

DELETE /invoices/{invoiceId}

Request

delete an invoice

Authentication

  • authToken in header

Parameters

  • invoiceId in path - string
    required
    invoice id

example

curl --request DELETE \
--url 'https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices/[invoiceId]' \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json

  • code    number
    required

  • data    object
    required

  • meta    object
    required

200

{
"code": 200,
"data": {
"id": 12
},
"meta": {
"message": "Success"
}
}

Create Invoice

POST /invoices

Request

Create Invoice

Authentication

  • authToken in header

Body

object | application/json
Extra Field Values

  • invoiceNumber    string
    required

    Invoice no.

  • type    string

    Invoice type

    Default: Invoice

  • dueDate    integer

    The due date for this invoice, specified as a Unix timestamp. If left empty, it will be set to the current date plus a pre-configured number of days (set in your B2B Edition control panel settings).

  • status    integer

    Invoice status. Possible values: 0: Open (default) 1: Partially paid 2: Completed

    The status will automatically be set to Completed (2) when the open balance becomes zero or negative.

    Allowed: 0 | 1 | 2

    Default: 0

  • orderNumber    string

    BigCommerce order ID associated with this invoice.

  • purchaseOrderNumber    string

    PO Number

  • originalBalance    object
    required

    Original balance

  • openBalance    object
    required

    Open balance , when it is <= 0, status will be auto set to 2

  • issuedAt    number

    When the invoice was created. The current timestamp is the default.

  • details    object

    Invoice details

  • source    number

    The source of the invoice. Possible values: 0: B2B Edition 1: External

    Allowed: 0 | 1

    Default: 0

  • customerId    string
    required

    B2B Edition Company ID

  • externalId    string

    ERP Invoice ID

  • externalCustomerId    string

    ERP Customer ID

  • channelId    integer

    BigCommerce Channel ID

  • externalPdfUrl    string

    The URL of an externally hosted PDF file to be associated with this invoice. The file size must not exceed 5 MB. Ensure that the file hosting service supports Cross-Origin Resource Sharing (CORS) to allow our system to access the file.

  • termsConditions    string

    Terms & Conditions. Visible on the default Invoice PDF.

  • extraFields    array[object]

Invoice body with details info

{
"invoiceNumber": "0000001",
"dueDate": 1619161808,
"status": 0,
"originalBalance": {
"code": "USD",
"value": 100
},
"openBalance": {
"code": "USD",
"value": 100
},
"issuedAt": 1619161808,
"details": {
"header": {
"costLines": [
{
"amount": {
"code": "USD",
"value": "90.00"
},
"description": "Subtotal"
},
{
"amount": {
"code": "USD",
"value": "10.00"
},
"description": "Freight"
},
{
"amount": {
"code": "USD",

Invoice body without details info

{
"invoiceNumber": "0000001",
"originalBalance": {
"code": "USD",
"value": 100
},
"openBalance": {
"code": "USD",
"value": 100
},
"customerId": "12345",
"channelId": 1
}

Response

OK

Body

object | application/json

  • code    number

    200

  • data    object

  • meta    object

200

{
"code": 200,
"data": {
"id": 12
},
"meta": {
"message": "Success"
}
}

400

{
"code": 400,
"data": {
"errMsg": "The invoice number already exists."
},
"meta": {
"message": "Bad Requests Error"
}
}

Get invoices

GET /invoices

Request

get invoices

Authentication

  • authToken in header

Parameters

  • offset in query - number
  • limit in query - number
  • orderBy in query - string
    "DESC" or "ASC"
    Example: DESC

    Allowed: DESC | ASC

  • sortBy in query - string
    Sort by the field value
    Example: invoiceNumber

    Allowed: invoiceNumber | createdAt | customerId | externalCustomerId | dueDate | updatedAt | isPendingPayment | openBalance | originalBalance | status

  • searchBy in query - string
    Filter by a field
    Example: invoiceNumber

    Allowed: invoiceNumber | type | orderNumber | purchaseOrderNumber | customerId | externalCustomerId

  • q in query - string
    You can perform keyword queries on fields corresponding to the value of "searchBy" or, if "searchBy" is empty, on all fields supported by "searchBy".
  • customerName in query - string
    Query by invoice B2B Edition company name
  • customerId in query - string
    Query by invoice B2B Edition company ID
  • status in query - integer
    Query by invoice status
    Example: 1

    Allowed: 0 | 1 | 2

  • beginDateAt in query - string
    Query by the created timestamp, along with the "endDateAt" parameter
  • endDateAt in query - string
    Query by the created timestamp, along with the with the "beginDateAt" parameter
  • externalId[] in query - array
    Query by the invoice external ID
    Type: array[number]
  • isIncludeExtraFields in query - string
    Determine if extra fields should show in the response

    Allowed: 0 | 1

  • channelIds in query - array
    BigCommerce Channel IDs
    Type: array[number]

example

curl --request GET \
--url https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json

  • code    number

  • data    array[object]

  • meta    object

example

{
"code": 200,
"data": [
{
"id": 33,
"customerId": "3",
"externalId": "123",
"externalCustomerId": "123",
"invoiceNumber": "00000033",
"type": "Invoice on Shipment",
"dueDate": 1619826907,
"status": 0,
"orderNumber": "132",
"purchaseOrderNumber": "123",
"details": {
"type": "StandardInvoiceDetails",
"header": {
"costLines": [
{
"amount": {
"code": "USD",
"value": "400.0000"
},
"description": "Subtotal"
},
{
"amount": {
"code": "USD",

Create invoice from order

POST /orders/{orderId}/invoices

Request

create invoice from B2B Edition order

Authentication

  • authToken in header

Parameters

  • orderId in path - number
    required
    B2B Edition order ID

Response

OK

Body

object | application/json

  • code    number
    required

  • data    object
    required

  • meta    object
    required

200

{
"code": 200,
"data": {
"invoiceNumber": "00000036",
"invoiceId": 36
},
"meta": {
"message": "SUCCESS"
}
}

404

{
"code": 404,
"data": {
"invoiceId": 36,
"invoiceNumber": "00000036",
"errMsg": "Order does not exist"
},
"meta": {
"message": "Not Found Error"
}
}

invoice download pdf

GET /invoices/{invoiceId}/download-pdf

Request

Get invoice download PDF

Authentication

  • authToken in header

Parameters

  • invoiceId in path - string
    required

example

curl --request GET \
--url 'https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices/[invoiceId]/download-pdf' \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json

  • code    integer

  • data    object

  • meta    object

Get invoice extra field configs

GET /invoices/extra-fields

Request

Get invoice extra field configs

Authentication

  • authToken in header

Parameters

  • offset in query - integer
    Pagination offset default: 0
  • limit in query with default of 10 - integer
    Pagination limit default: 10

example

curl --request GET \
--url https://api-b2b.bigcommerce.com/api/v3/io/ip/invoices/extra-fields \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json
Response for successful request

  • code    integer

    Response code of success request.
    Example: 200

  • meta    object

    Used to response pagination information
    Example: {"pagination":{"limit":10,"offset":0,"totalCount":1}}

  • data    array[object]

example

{
"code": 200,
"meta": {
"pagination": {
"limit": 10,
"offset": 0,
"totalCount": 1
}
},
"data": [
{
"id": 0,
"uuid": "string",
"fieldName": "string",
"fieldType": 0,
"isRequired": true,
"isUnique": true,
"visibleToEnduser": true,
"configType": 1,
"defaultValue": "string",
"maximumLength": "string",
"numberOfRows": "string",
"maximumValue": "string",
"listOfValue": [
"string"
]
}
]
}
Did you find what you were looking for?
Invoice ManagementGet invoice detail