logo

Create an invoice

Create an invoice.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json

Invoice resource.

currency
required
string = 3 characters

ISO 4217 alphabetic currency code.

websiteId
required
string <= 50 characters

The website ID.

customerId
required
string <= 50 characters

The customer resource ID. Defaults to UUID v4.

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.

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.

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.

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.

autopayScheduledTime
string <date-time>

Invoice autopay scheduled time.

dueTime
string <date-time>

Invoice due time.

object

The invoice retry instruction.

required
Array of objects non-empty
Array (non-empty)
required
object (InvoiceRetryScheduleInstruction)

The calculation instruction of scheduled time.

object (InvoiceRetryAmountAdjustmentInstruction)
tryBackupInstruments
boolean
Default: false

Whether to use backup payment instruments on invoice payment retry or not.

afterAttemptPolicies
required
Array of strings

The policy on the attempt finishes.

Items Value: "change-subscription-renewal-time"
afterRetryEndPolicies
required
Array of strings

The policy on the retry ends.

Items Enum: "abandon-invoice" "cancel-subscription"
Responses
201

Invoice was created.

Response Headers
Location
string <uri>

The location of the related resource.

Example: "https://api.rebilly.com/example"
Response Schema: application/json
currency
required
string = 3 characters

ISO 4217 alphabetic currency code.

websiteId
required
string <= 50 characters

The website ID.

customerId
required
string <= 50 characters

The customer resource ID. Defaults to UUID v4.

id
string <= 50 characters

The invoice ID.

invoiceNumber
integer

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

subscriptionId
string <= 50 characters

The related order's ID if available, otherwise null.

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.

stateAmount
number or null <double>

Amount of sales tax to collect for the state.

countyAmount
number or null <double>

Amount of sales tax to collect for the county.

cityAmount
number or null <double>

Amount of sales tax to collect for the city.

specialDistrictAmount
number or null <double>

Amount of sales tax to collect for the special district.

object or null

Jurisdiction names for the 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
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

The website identifier string.

description
string

Invoice item's description.

quantity
integer

Invoice item's quantity.

price
number <double>

Invoice item's total price.

productId
string <= 50 characters

The product's ID.

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>

Invoice item created time.

updatedTime
string <date-time> (UpdatedTime)

Read-only timestamp updates when the resource is updated.

object

Invoice item tax.

Array of Self (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

Coupon's ID.

redemptionId
string <= 50 characters

Redemption ID.

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" "partially-paid" "past-due" "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>

Invoice abandoned time.

voidedTime
string <date-time>

Invoice voided time.

paidTime
string <date-time>

Invoice paid time.

dueTime
string <date-time>

Invoice due time.

issuedTime
string <date-time>

Invoice issued time.

createdTime
string <date-time>

Invoice created time.

updatedTime
string <date-time>

Read-only timestamp updates when the resource is updated.

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 (Transaction)

Invoice transactions array.

Array
id
string <= 50 characters

The transaction ID.

websiteId
string <= 50 characters

The website ID.

customerId
string <= 50 characters

The customer 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

The parent's transaction ID.

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

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

Payment Gateway name, available only after the gateway is selected for the transaction.

Enum: "A1Gateway" "ACI" "Adyen" "Airpay" "AmazonPay" "AmexVPC" "ApcoPay" "AsiaPaymentGateway" "AstroPayCard" "AuthorizeNet" … 166 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>

Transaction processed time.

createdTime
string <date-time>

Transaction created time.

updatedTime
string <date-time>

Read-only timestamp updates when the resource is updated.

gatewayAccountId
string <= 50 characters

The transaction's Gateway Account ID.

gatewayTransactionId
string <= 50 characters

The gateway's transaction ID.

object

The related gateway information.

acquirerName
string

Acquirer name, available only when transaction use gateway, else null.

Enum: "Adyen" "ACI" "Alipay" "AIB" "Airpay" "AmazonPay" "ApcoPay" "AsiaPaymentGateway" "AstroPay Card" "Awepay" … 165 more
method
string
Deprecated

Payment Method. Use paymentInstrument.method instead.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 156 more
velocity
integer

The number of transactions by the same customer in the past 24 hours.

revision
integer

The number of times the transaction data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

object or null

Transaction reference data.

bin
string <bin>

Payment Card BIN.

Vaulted instrument (object) or Alternative Instrument (object) or Cash (object) or Check (object) (PaymentInstrumentValueObject)
hasDcc
boolean

True if transaction has Dynamic Currency Conversion applied.

object

Dynamic Currency Conversion detailed information. Null if hasDcc is false.

hasBumpOffer
boolean

True if transaction has a Bump offer.

object

Bump offer information. Null if hasBumpOffer is false.

riskScore
integer

The transaction's risk score.

object (Risk metadata)

Risk metadata.

notificationUrl
string <uri> (TransactionNotificationUrl)

The URL where a server-to-server POST notification will be sent. It will be sent when the transaction's result is finalized after a timeout or an offsite interaction. Do not trust the notification; follow with a GET request to confirm the result of the transaction. Please respond with a 2xx HTTP status code, or we will reattempt the request again. The 2 placeholders are available to use in this URI: {id} and {result}.

isDisputed
boolean

True if transaction is disputed.

disputeTime
string or null <date-time>

Time the dispute was created, else null.

disputeStatus
string or null

The dispute's status, else null.

Enum: "response-needed" "under-review" "forfeited" "won" "lost" "unknown"
isReconciled
boolean

True if the transaction has been verified with gateway batch data.

isProcessedOutside
boolean

True if the transaction was processed outside of Rebilly.

isMerchantInitiated
boolean

True if the transaction was initiated by the merchant.

hadDiscrepancy
boolean

True if the transaction has been updated due to a discrepancy with its. source of truth.

orderId
string
Deprecated

The transaction's order ID. This ID must be unique within a 24 hour period. This field was renamed to the requestId.

arn
string

The acquirer reference number.

reportAmount
number <double>

Transaction amount converted to organization selected report currency.

reportCurrency
string = 3 characters

ISO 4217 alphabetic currency code.

settlementTime
string or null <date-time>

The time that the transaction was settled by the banking instuition.

discrepancyTime
string or null <date-time>

The time of the most recent discrepancy on the transaction.

object or null (LimitAmount)
Array of Self (object) or WebsiteLink (object) or CustomerLink (object) or GatewayAccountLink (object) or PaymentCardLink (object) or ParentTransactionLink (object) or LeadSourceLink (object) or ApprovalUrlLink (object) or RefundUrlLink (object) or TransactionUpdateUrlLink (object) or DisputeLink (object) or InvoicesLink (object) or QueryUrlLink (object) or TransactionRedirectUrlLink (object) non-empty

The links related to resource.

Array of ParentTransactionEmbed (object) or GatewayAccountEmbed (object) or CustomerEmbed (object) or LeadSourceEmbed (object) or WebsiteEmbed (object) or PaymentCardEmbed (object) or BankAccountEmbed (object) or InvoicesEmbed (object) or ChildTransactionsEmbed (object) non-empty

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

object

The invoice retry instruction.

required
Array of objects non-empty
Array (non-empty)
required
object (InvoiceRetryScheduleInstruction)

The calculation instruction of scheduled time.

object (InvoiceRetryAmountAdjustmentInstruction)
tryBackupInstruments
boolean
Default: false

Whether to use backup payment instruments on invoice payment retry or not.

afterAttemptPolicies
required
Array of strings

The policy on the attempt finishes.

Items Value: "change-subscription-renewal-time"
afterRetryEndPolicies
required
Array of strings

The policy on the retry ends.

Items Enum: "abandon-invoice" "cancel-subscription"
revision
integer

The number of times the invoice data has been modified. The revision is useful when analyzing webhook data to determine if the change takes precedence over the current representation.

type
string

Invoice type.

Enum: "initial" "renewal" "interim" "cancellation" "one-time" "refund" "charge" "one-time-sale"
dueReminderTime
string or null <date-time>

Time past due reminder event will be triggered.

dueReminderNumber
integer or null

Number of past due reminder events triggered.

Array of Self (object) or CustomerLink (object) or WebsiteLink (object) or OrganizationLink (object) or LeadSourceLink (object) or TransactionAllocationsLink (object) or RecalculateInvoiceLink (object) or SubscriptionLink (object) non-empty

The links related to resource.

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

The link URL.

rel
required
string

The link type.

Value: "self"
Array of CustomerEmbed (object) or WebsiteEmbed (object) or OrganizationEmbed (object) or LeadSourceEmbed (object) or ShippingRateEmbed (object) non-empty

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

Array (non-empty)
Any of:

Customer object.

object (Customer)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/invoices
Request samples
application/json
{
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "currency": "USD",
  • "shipping": {
    },
  • "tax": {
    },
  • "billingAddress": {
    },
  • "deliveryAddress": {
    },
  • "poNumber": "PO123456",
  • "notes": "string",
  • "autopayScheduledTime": "2019-08-24T14:15:22Z",
  • "dueTime": "2019-08-24T14:15:22Z",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "retryInstruction": {
    }
}
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",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "transactions": [
    ],
  • "retryInstruction": {
    },
  • "revision": 0,
  • "type": "initial",
  • "dueReminderTime": "2019-08-24T14:15:22Z",
  • "dueReminderNumber": 0,
  • "_links": [
    ],
  • "_embedded": [
    ]
}
➔ Next to Retrieve an invoice