Invoices

Invoices leave a record for both you and your customer of the products sold.

Retrieve a list of invoices

Retrieve a list of invoices.

SecurityCustomerJWT
Request
query Parameters
filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

q
string

The partial search of the text fields.

Responses
200

Invoices were retrieved successfuly.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
currency
required
string 3 characters

ISO 4217 alphabetic currency code.

websiteId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

invoiceNumber
integer

An auto-incrementing number based on the sequence of invoices for any particular customer.

subscriptionId
string <= 50 characters

The resource ID. Defaults to UUID v4.

amount
number <double>

The invoice's amount.

amountDue
number <double>

The invoice's due amount.

subtotalAmount
number <double>

The invoice's subtotal amount.

discountAmount
number <double>

The invoice's discounts amount.

object (Shipping)

Shipping settings.

calculator
required
string

Shipping calculator.

amount
required
integer

Shipping amount.

object (InvoiceTax)

Invoice taxes.

calculator
required
string

Tax calculator.

required
Array of objects

Taxes applied to this invoice.

amount
integer

A sum of all invoice taxes.

object

Invoice's billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array of objects (ContactEmails)

The list of emails.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

object

Invoice's delivery address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array of objects (ContactEmails)

The list of emails.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

poNumber
string or null

Purchase order number which will be displayed on the invoice.

notes
string

Notes for the customer which will be displayed on the invoice.

Array of objects (InvoiceItem)

Invoice items array.

Array
type
required
string

Invoice item's type.

Enum: "debit" "credit"
unitPrice
required
number <double>

Invoice item's price.

id
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

description
string

Invoice item's description.

quantity
integer

Invoice item's quantity.

price
number <double>

Invoice item's total price.

productId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

discountAmount
number <double>

Invoice item discount amount.

periodStartTime
string <date-time>

Start time.

periodEndTime
string <date-time>

End time.

periodNumber
integer

Invoice item subscription order period number.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

object

Invoice item tax.

Array of SelfLink (object) or ProductLink (object) non-empty

The links related to resource.

Array of ProductEmbed (object) or PlanEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array of objects

Discounts applied.

Array
couponId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

redemptionId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

amount
number <double>

Total amount that was discounted by this Coupon.

description
string

Discount description.

context
string (DiscountContext)
Default: "items"

The context in which the discount applies.

Enum: Description
items

items (less discounts)

shipping

shipping (less discounts)

items-and-shipping

items and shipping (less discounts)

autopayScheduledTime
string <date-time>

Invoice autopay scheduled time.

autopayRetryNumber
integer >= 0
Default: 0

Invoice autopay retry number.

status
string

Invoice status.

Enum: "draft" "unpaid" "paid" "past-due" "delinquent" "abandoned" "voided" "partially-refunded" "refunded" "disputed"
delinquentCollectionPeriod
integer

Delinquent collection period - difference between paidTime and dueTime in days.

collectionPeriod
integer

Collection period - difference between paidTime and issuedTime in days.

abandonedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

voidedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

paidTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

dueTime
string <date-time>

Invoice due time.

issuedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

paymentFormUrl
string <url>

URL where the customer can be redirected to pay for the invoice with one of the methods which are available for this customer. It's an alternative to creating a new transaction with empty methods.

Array of objects (StorefrontTransaction)

Invoice transactions array.

Array
id
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

websiteId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

type
string

Transaction type.

Enum: "3ds-authentication" "authorize" "capture" "credit" "refund" "sale" "setup" "void"
status
string

Transaction status.

Enum: "completed" "conn-error" "disputed" "never-sent" "offsite" "partially-refunded" "pending" "refunded" "sending" "suspended" … 6 more
result
string

Transaction result.

Enum: "abandoned" "approved" "canceled" "declined" "unknown"
amount
number <double>

The transaction's amount.

currency
string 3 characters

ISO 4217 alphabetic currency code.

purchaseAmount
number <double>

The amount actually purchased which may have differed from the originally requested amount in case of an adjustment.

purchaseCurrency
string 3 characters

ISO 4217 alphabetic currency code.

requestAmount
number <double>

The amount in the payment request. If adjusted, the purchase amount and billing amount may vary from it.

requestCurrency
string 3 characters

ISO 4217 alphabetic currency code.

parentTransactionId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

childTransactions
Array of strings (ResourceId)

The child transaction IDs.

invoiceIds
Array of strings (ResourceId)

The invoice IDs related to transaction.

subscriptionIds
Array of strings (ResourceId)

The orders IDs related to transaction's invoice(s).

planIds
Array of strings (ResourceId)

The plan IDs related to transaction's order(s).

isRebill
boolean
rebillNumber
integer

The transaction's rebill number.

object (InstrumentReference)
object

Billing address.

has3ds
boolean
object
redirectUrl
string <uri>

The URL to redirect the end-user when an offsite transaction is completed. Defaults to the website's configured URL.

retryNumber
integer

The position in the sequence of retries.

isRetry
boolean

True if this transaction is retry.

billingDescriptor
string

The billing descriptor that appears on the periodic billing statement. Commonly 12 or fewer characters for a credit card statement.

description
string <= 255 characters

The payment description.

requestId
string

The transaction's request ID. This ID must be unique within a 24 hour period. Use this field to prevent duplicated transactions.

hasAmountAdjustment
boolean

True if transaction has amount adjustment.

gatewayName
string

The payment gateway name.

Enum: "A1Gateway" "ACI" "Adyen" "Airpay" "AmazonPay" "AmexVPC" "ApcoPay" "AsiaPaymentGateway" "AstroPayCard" "AuthorizeNet" … 162 more
customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

processedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

approvalUrl
string <uri>

The URL to redirect the end-customer when transaction status is waiting-approval or offsite.

token
string

The session's token used for authentication. It would allow to visit created order, invoice and transaction.

Array of SelfLink (object) or ApprovalUrlLink (object) non-empty

The links related to resource.

Array of SelfLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/invoices
Request samples
curl -i -X GET \
  'https://api-sandbox.rebilly.com/storefront/invoices?filter=string&sort=string&limit=1000&offset=0&q=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
application/json
[
  • {
    }
]

Retrieve a Invoice

Retrieve a invoice with specified ID.

SecurityCustomerJWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
200

Invoice was retrieved successfuly.

Response Schema: application/json
currency
required
string 3 characters

ISO 4217 alphabetic currency code.

websiteId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

invoiceNumber
integer

An auto-incrementing number based on the sequence of invoices for any particular customer.

subscriptionId
string <= 50 characters

The resource ID. Defaults to UUID v4.

amount
number <double>

The invoice's amount.

amountDue
number <double>

The invoice's due amount.

subtotalAmount
number <double>

The invoice's subtotal amount.

discountAmount
number <double>

The invoice's discounts amount.

object (Shipping)

Shipping settings.

calculator
required
string

Shipping calculator.

amount
required
integer

Shipping amount.

object (InvoiceTax)

Invoice taxes.

calculator
required
string

Tax calculator.

required
Array of objects

Taxes applied to this invoice.

Array
amount
required
number <double>

Tax amount.

description
required
string

Tax description.

rate
number or null <double>

Tax rate.

amount
integer

A sum of all invoice taxes.

object

Invoice's billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

object

Invoice's delivery address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

poNumber
string or null

Purchase order number which will be displayed on the invoice.

notes
string

Notes for the customer which will be displayed on the invoice.

Array of objects (InvoiceItem)

Invoice items array.

Array
type
required
string

Invoice item's type.

Enum: "debit" "credit"
unitPrice
required
number <double>

Invoice item's price.

id
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

description
string

Invoice item's description.

quantity
integer

Invoice item's quantity.

price
number <double>

Invoice item's total price.

productId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

discountAmount
number <double>

Invoice item discount amount.

periodStartTime
string <date-time>

Start time.

periodEndTime
string <date-time>

End time.

periodNumber
integer

Invoice item subscription order period number.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

object

Invoice item tax.

Array of SelfLink (object) or ProductLink (object) non-empty

The links related to resource.

Array of ProductEmbed (object) or PlanEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array of objects

Discounts applied.

Array
couponId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

redemptionId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

amount
number <double>

Total amount that was discounted by this Coupon.

description
string

Discount description.

context
string (DiscountContext)
Default: "items"

The context in which the discount applies.

Enum: Description
items

items (less discounts)

shipping

shipping (less discounts)

items-and-shipping

items and shipping (less discounts)

autopayScheduledTime
string <date-time>

Invoice autopay scheduled time.

autopayRetryNumber
integer >= 0
Default: 0

Invoice autopay retry number.

status
string

Invoice status.

Enum: "draft" "unpaid" "paid" "past-due" "delinquent" "abandoned" "voided" "partially-refunded" "refunded" "disputed"
delinquentCollectionPeriod
integer

Delinquent collection period - difference between paidTime and dueTime in days.

collectionPeriod
integer

Collection period - difference between paidTime and issuedTime in days.

abandonedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

voidedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

paidTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

dueTime
string <date-time>

Invoice due time.

issuedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

paymentFormUrl
string <url>

URL where the customer can be redirected to pay for the invoice with one of the methods which are available for this customer. It's an alternative to creating a new transaction with empty methods.

Array of objects (StorefrontTransaction)

Invoice transactions array.

Array
id
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

websiteId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

type
string

Transaction type.

Enum: "3ds-authentication" "authorize" "capture" "credit" "refund" "sale" "setup" "void"
status
string

Transaction status.

Enum: "completed" "conn-error" "disputed" "never-sent" "offsite" "partially-refunded" "pending" "refunded" "sending" "suspended" … 6 more
result
string

Transaction result.

Enum: "abandoned" "approved" "canceled" "declined" "unknown"
amount
number <double>

The transaction's amount.

currency
string 3 characters

ISO 4217 alphabetic currency code.

purchaseAmount
number <double>

The amount actually purchased which may have differed from the originally requested amount in case of an adjustment.

purchaseCurrency
string 3 characters

ISO 4217 alphabetic currency code.

requestAmount
number <double>

The amount in the payment request. If adjusted, the purchase amount and billing amount may vary from it.

requestCurrency
string 3 characters

ISO 4217 alphabetic currency code.

parentTransactionId
string <= 50 characters Recursive

The resource ID. Defaults to UUID v4.

childTransactions
Array of strings (ResourceId)

The child transaction IDs.

invoiceIds
Array of strings (ResourceId)

The invoice IDs related to transaction.

subscriptionIds
Array of strings (ResourceId)

The orders IDs related to transaction's invoice(s).

planIds
Array of strings (ResourceId)

The plan IDs related to transaction's order(s).

isRebill
boolean
rebillNumber
integer

The transaction's rebill number.

object (InstrumentReference)
object

Billing address.

has3ds
boolean
object
redirectUrl
string <uri>

The URL to redirect the end-user when an offsite transaction is completed. Defaults to the website's configured URL.

retryNumber
integer

The position in the sequence of retries.

isRetry
boolean

True if this transaction is retry.

billingDescriptor
string

The billing descriptor that appears on the periodic billing statement. Commonly 12 or fewer characters for a credit card statement.

description
string <= 255 characters

The payment description.

requestId
string

The transaction's request ID. This ID must be unique within a 24 hour period. Use this field to prevent duplicated transactions.

hasAmountAdjustment
boolean

True if transaction has amount adjustment.

gatewayName
string

The payment gateway name.

Enum: "A1Gateway" "ACI" "Adyen" "Airpay" "AmazonPay" "AmexVPC" "ApcoPay" "AsiaPaymentGateway" "AstroPayCard" "AuthorizeNet" … 162 more
customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

processedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

approvalUrl
string <uri>

The URL to redirect the end-customer when transaction status is waiting-approval or offsite.

token
string

The session's token used for authentication. It would allow to visit created order, invoice and transaction.

Array of SelfLink (object) or ApprovalUrlLink (object) non-empty

The links related to resource.

Array of SelfLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/invoices/{id}
Request samples
curl -i -X GET \
  'https://api-sandbox.rebilly.com/storefront/invoices/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "invoiceNumber": 0,
  • "subscriptionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "currency": "USD",
  • "amount": 0,
  • "amountDue": 0,
  • "subtotalAmount": 0,
  • "discountAmount": 0,
  • "shipping": {
    },
  • "tax": {
    },
  • "billingAddress": {
    },
  • "deliveryAddress": {
    },
  • "poNumber": "PO123456",
  • "notes": "string",
  • "items": [
    ],
  • "discounts": [
    ],
  • "autopayScheduledTime": "2019-08-24T14:15:22Z",
  • "autopayRetryNumber": 0,
  • "status": "draft",
  • "delinquentCollectionPeriod": 0,
  • "collectionPeriod": 0,
  • "abandonedTime": "2019-08-24T14:15:22Z",
  • "voidedTime": "2019-08-24T14:15:22Z",
  • "paidTime": "2019-08-24T14:15:22Z",
  • "dueTime": "2019-08-24T14:15:22Z",
  • "issuedTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "paymentFormUrl": "string",
  • "transactions": [
    ],
  • "_links": [
    ]
}