Retrieve an upcoming invoice

Retrieves an upcoming invoice for a specified subscription order.

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

Resource identifier string.

query Parameters
expand
string

Expands a request to include embedded objects within the _embedded property of the response. This field accepts a comma-separated list of objects.

For more information, see Expand to include embedded objects.

Responses
200

Upcoming invoice retrieved.

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

Currency code in ISO 4217 format.

websiteId
required
string (WebsiteId) <= 50 characters

Unique website identifier string. A website is where an organization obtains a customer through a subscription. For more information, see Obtain an organization ID and website ID.

customerId
required
string <= 50 characters

Customer resource ID. Defaults to UUID v4.

id
string <= 50 characters

ID of the invoice.

invoiceNumber
integer

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

subscriptionId
string <= 50 characters

ID of the related subscription order, if available. This field is null if there are no related subscription orders.

amount
number <double>

Amount of the invoice.

amountDue
number <double>

Amount that is due on the invoice.

subtotalAmount
number <double>

Subtotal amount of the invoice.

discountAmount
number <double>

Discount amount that is applied to the invoice.

object (Shipping)

Shipping settings.

calculator
required
string

Shipping calculator.

amount
required
integer

Shipping amount.

object (InvoiceTax)

Invoice taxes.

calculator
required
string

Type of tax calculator.

required
Array of objects

Taxes applied to this invoice.

Array
amount
required
number <double>

Amount of tax.

description
required
string

Description of the tax.

rate
number or null <double>

Overall sales tax rate which includes state, county, city and district tax.

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.

stateRate
number or null <double>

State sales tax rate for given location.

countyRate
number or null <double>

County sales tax rate for given location.

cityRate
number or null <double>

City sales tax rate for given location.

specialDistrictRate
number or null <double>

Special district sales tax rate for given location.

object or null

Jurisdiction names for the invoice.

amount
integer

Total amount of all invoice taxes.

object

Billing address of the invoice.

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

Contact's first name.

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

Contact's last name.

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

Contact's organization.

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

First line of the contact's street address.

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

Second line of the contact's street address.

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

Contact's city of residence.

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

Contact's region of residence.

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

Contact's country of residence in ISO 3166 alpha-2 country code. For examples, see ISO.org.

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

Contact's postal code.

Array of objects (ContactPhoneNumbers)

List of phone numbers associated with the contact.

Array
label
required
string <= 45 characters

Phone number label or name.

value
required
string <= 50 characters

Phone number value.

primary
boolean

Specifies whether the phone number is the contact's primary phone number.

Array of objects (ContactEmails)

List of email addresses associated with the contact.

Array
label
required
string <= 45 characters

Email label or name.

value
required
string <email> <= 255 characters

Email address value.

primary
boolean

Specifies whether the email address is the contact's primary email address.

dob
string or null <date>

Contact's date of birth in ISO-8601 YYYY-MM-DD format.

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

Contact's job title.

hash
string <= 40 characters

Use this value to compare contacts for identical attribute values.

object

Delivery address of the invoice.

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

Contact's first name.

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

Contact's last name.

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

Contact's organization.

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

First line of the contact's street address.

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

Second line of the contact's street address.

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

Contact's city of residence.

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

Contact's region of residence.

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

Contact's country of residence in ISO 3166 alpha-2 country code. For examples, see ISO.org.

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

Contact's postal code.

Array of objects (ContactPhoneNumbers)

List of phone numbers associated with the contact.

Array
label
required
string <= 45 characters

Phone number label or name.

value
required
string <= 50 characters

Phone number value.

primary
boolean

Specifies whether the phone number is the contact's primary phone number.

Array of objects (ContactEmails)

List of email addresses associated with the contact.

Array
label
required
string <= 45 characters

Email label or name.

value
required
string <email> <= 255 characters

Email address value.

primary
boolean

Specifies whether the email address is the contact's primary email address.

dob
string or null <date>

Contact's date of birth in ISO-8601 YYYY-MM-DD format.

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

Contact's job title.

hash
string <= 40 characters

Use this value to compare contacts for identical attribute values.

poNumber
string or null

Purchase order number that is displayed on the invoice.

notes
string

Notes for the customer that are displayed on the invoice.

Array of objects (InvoiceItem)

Invoice items array.

Array
type
required
string

Type of invoice item.

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

Unit price of the invoice item.

id
string <= 50 characters

Unique website identifier string. A website is where an organization obtains a customer through a subscription. For more information, see Obtain an organization ID and website ID.

description
string

Description of the invoice item.

quantity
integer

Quantity of the invoice item.

price
number <double>

Total price of the invoice item.

productId
string <= 50 characters

ID of the product.

discountAmount
number <double>

Discount amount applied to the invoice item.

periodStartTime
string <date-time>

Date and time when the billing period starts.

periodEndTime
string <date-time>

Date and time when the billing period ends.

periodNumber
integer

Number of subscription order billing periods in which the invoice item has been included.

createdTime
string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime
string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

object

Invoice item tax.

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

Related resource links.

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

Embedded objects that are requested by the expand query parameter.

Array of objects

Discounts applied.

Array
couponId
string <= 50 characters

ID of the coupon.

redemptionId
string <= 50 characters

ID of the redemption.

amount
number <double>

Total amount discounted by this coupon.

description
string

Description of the discount.

context
string (DiscountContext)
Default: "items"

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>

Date and time when an automatic payment (autopay) is scheduled.

autopayRetryNumber
integer >= 0
Default: 0

Number of times that an automatic payment (autopay) has been attempted on an invoice.

status
string

Status of the invoice.

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

Length of time, in days, between when the invoice is due and when the invoice is paid.

collectionPeriod
integer

Length of time, in days, between when the invoice is issued and when the invoice is paid.

abandonedTime
string <date-time>

Date and time when the invoice is abandoned.

voidedTime
string <date-time>

Date and time when the invoice is voided.

paidTime
string <date-time>

Date and time when the invoice is paid.

dueTime
string <date-time>

Date and time when the invoice is due for payment.

issuedTime
string <date-time>

Date and time when the invoice is issued.

createdTime
string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime
string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

paymentFormUrl
string <url>

URL where the customer is redirected to pay the invoice using one of the methods which are available to the customer. This is an alternative to creating a new transaction with empty methods.

Array of objects (Transaction)

Invoice transactions array.

Array
id
string <= 50 characters

Unique transaction identifier string.

websiteId
string <= 50 characters

Unique website identifier string. A website is where an organization obtains a customer through a subscription. For more information, see Obtain an organization ID and website ID.

customerId
string <= 50 characters

Customer resource ID. Defaults to UUID v4.

type
string

Type of transaction.

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

Status of a transaction.

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

Result of a transaction.

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

Total amount of a transaction.

currency
string = 3 characters

Currency code in ISO 4217 format.

purchaseAmount
number <double>

Amount by which the purchase is completed. If an adjustment occurs, the purchased amount may differ from the requested amount.

purchaseCurrency
string = 3 characters

Currency code in ISO 4217 format.

requestAmount
number <double>

Amount of the payment request. If an adjustment occurs, the purchased amount may differ from the billing amount.

requestCurrency
string = 3 characters

Currency code in ISO 4217 format.

parentTransactionId
string <= 50 characters

ID of the parent transaction.

childTransactions
Array of strings (ResourceId)

IDs of child transactions.

invoiceIds
Array of strings (ResourceId)

Related invoice IDs.

subscriptionIds
Array of strings (ResourceId)

Subscription IDs of invoices that are related to the transaction.

planIds
Array of strings (ResourceId)

Plan IDs of orders that are related to the transaction.

isRebill
boolean

Specifies whether the transaction is one of a number of recurring payments in a subscription, excluding trials or setup fees.

rebillNumber
integer

Rebill number of the transaction. A rebill number is the number of recurring payments in a subscription, excluding trials or setup fees.

object

Billing address.

has3ds
boolean

Specifies whether the transaction uses 3D Secure.

object (ThreeDSecureResult)

Authentication object.

redirectUrl
string <uri>

URL where the end-user is redirected to when an offsite transaction is completed. The default value is the website's configured URL.

retryNumber
integer

Position of the transaction in the sequence of retries.

isRetry
boolean

Specifies whether a transaction is a retry.

billingDescriptor
string

Billing descriptor that appears on the periodic billing statement. For a credit card statement, this field commonly contains 12 or fewer characters.

description
string <= 255 characters

Description of the payment.

requestId
string

Request ID of the transaction. This ID must be unique within a 24 hour period. Use this field to prevent duplicated transactions.

hasAmountAdjustment
boolean

Specifies whether the transaction has amount adjustment.

gatewayName
string

Name of the payment gateway that processed, or is selected to process, the transaction. This value is only available after a gateway is selected for the transaction.

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

Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see Custom fields.

processedTime
string <date-time>

Date and time when the transaction is processed.

createdTime
string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime
string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

gatewayAccountId
string <= 50 characters

ID of the gateway account that processed the transaction.

gatewayTransactionId
string <= 50 characters

ID of the gateway transaction.

object

Related gateway information.

acquirerName
string

Acquirer name. This value is only available when a transaction uses a payment gateway. If a transaction does not use a payment gateway, this value is null.

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

Payment method.

Note: Use paymentInstrument.method instead.

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

Number of transactions by the same customer in the past 24 hours.

revision
integer

Number of times the transaction data has been modified.

This revision number 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

Specifies whether Dynamic Currency Conversion (DCC) applies to the transaction.

object

Detailed Dynamic currency conversion (DCC). If DCC is not applied to the transaction, this value is null.

hasBumpOffer
boolean

Specifies whether a transaction has a bump offer.

object

Bump offer information. If the transaction does not have an associated bump offer, this value is null.

riskScore
integer

Risk score for the transaction.

object (Risk metadata)

Risk metadata.

notificationUrl
string <uri> (TransactionNotificationUrl)

URL where a server-to-server POST notification is sent. This notification is sent when the transaction result is finalized after a timeout or an offsite interaction.

Do not trust this notification alone, complete a GET request to confirm the result of the transaction. To ensure the request is not reattempted, when the result is confirmed, respond with a 2xx HTTP status code.

The following placeholders are available to use in this URI: {id} and {result}.

isDisputed
boolean

Specifies whether a transaction is disputed.

disputeTime
string or null <date-time>

Date and time when the dispute is created. If the transaction is not disputed, this value is null.

disputeStatus
string or null

Status of the dispute.

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

Specifies whether the transaction is verified with gateway batch data. If the transaction is not disputed, this value is null.

isProcessedOutside
boolean

Specifies whether the transaction is processed outside of Rebilly.

isMerchantInitiated
boolean

Specifies whether the transaction is initiated by the merchant.

hadDiscrepancy
boolean

Specifies whether the transaction is updated due to a discrepancy with its source of truth.

orderId
string
Deprecated

Order ID of the transaction. This ID must be unique within a 24 hour period.

Note: Use the requestId field instead.

arn
string

Acquirer reference number.

reportAmount
number <double>

Transaction amount converted to the report currency of the organization.

reportCurrency
string = 3 characters

Currency code in ISO 4217 format.

settlementTime
string or null <date-time>

Date and time when the transaction is settled by the banking institution.

discrepancyTime
string or null <date-time>

Date and 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

Related resource links.

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

Embedded objects that are requested by the expand query parameter.

object

Invoice payment retry instruction. This object specifies how to proceed if a payment related to the invoice fails.

required
Array of objects non-empty

Describes the retry instruction.

Array (non-empty)
required
object (InvoiceRetryScheduleInstruction)

Specifies when the payment retry instruction is performed.

object (InvoiceRetryAmountAdjustmentInstruction)

Specifies whether the payment amount must be adjusted for the retry.

tryBackupInstruments
boolean
Default: false

Specifies whether to use backup payment instruments on an invoice payment retry.

afterAttemptPolicies
required
Array of strings

Describes the action to take when a payment attempt concludes, and payment is not collected.

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

Describes the action to take when all scheduled payment retries, in a retry instruction, have concluded and payment is not collected.

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

Number of times the invoice data has been modified.

Use the revision number when analyzing webhook data to determine if a change should take precedence over the current representation.

type
string

Type of invoice.

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

Date and time when a past due reminder event is triggered.

dueReminderNumber
integer or null

Number of past due reminder events that have been 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

Related resource links.

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

Link URL.

rel
required
string

Type of link.

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

Embedded objects that are requested by the expand query parameter.

Array (non-empty)
Any of:

Customer object.

object (Customer)
401

Unauthorized access. Invalid credentials used.

403

Access forbidden.

404

Resource not found.

get/subscriptions/{id}/upcoming-invoice
Request samples
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "example.com",
  • "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": [
    ]
}