Invoice
Private Invoice API endpoints
An API endpoint to get list of invoices.
Query parameters
pageoptionalintegerPage
per_pageoptionalintegerEntities per page
customer_idoptionalintegerFilter by customer ID
subscription_idoptionalintegerFilter by subscription ID
created_at[gte]optionalstringFilter to include only invoices with a creation date on or after the given date.
created_at[lte]optionalstringFilter to include only invoices with a creation date on or before the given date.
start_dateoptionalstringDeprecatedDeprecated alias of created_at[gte]. When both arrive, created_at[gte] wins.
end_dateoptionalstringDeprecatedDeprecated alias of created_at[lte]. When both arrive, created_at[lte] wins.
statusesoptionalstring[]Filter by invoice status
sort[field]optionalstringField to sort by. Required whenever any sort[...] key is present, so sending sort[direction] on its own returns 422. Send sort as an object (sort[field]=created_at), never as a scalar. When sort is omitted the list is ordered by id descending.
Possible values: id, created_at.
sort[direction]optionalstringSort direction; defaults to asc.
Possible values: asc, desc.
Defaults to "asc".
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
Returnsobject
Invoices list response
Error responses
422objectA query parameter failed validation: page below 1, per_page outside 1 to 100, a customer_id or subscription_id that does not belong to the shop, an unknown statuses[] value, a date not in 2022-02-24T04:00:00 format, sort[direction] without sort[field], an unknown sort field or direction, or a non-array expand[].
curl https://api.subbly.co/private/v1/invoices \
-H 'X-API-KEY: <api-key>'{
"pagination": {
"current_page": 1,
"last_page": 2,
"from": 1,
"to": 1,
"total": 20
},
"data": [
{
"id": 1,
"subscription_id": 1,
"subscription": {
"id": 1,
"customer_id": 1,
"customer": {},
"referred_by": 1,
"product_id": 1,
"product": {},
"quantity": 1,
"shipping_address_id": 1,
"shipping_address": {},
"shipping_method_id": 1,
"shipping_method": {},
"shipping_carrier_id": 1,
"shipping_carrier_service": "shipping_carrier_service",
"billing_address_id": 1,
"billing_address": {},
"payment_method_id": 1,
"payment_method": {},
"currency_code": "USD",
"survey": {},
"preferences": {},
"bundle": {},
"gift": {
"message": "message",
"starts_at": "2022-02-24T04:00:00.000000Z",
"order_limit": 1
},
"commitment_term_total_payments": 1,
"cancel_at_end_of_commitment": true,
"next_payment_date": "2023-04-23T00:45:00.000000Z",
"starts_at": "2023-04-23T00:45:00.000000Z",
"active": true,
"paused": false,
"paused_at": null,
"skipping_until": null,
"waiting_until": null,
"past_due": false,
"successful_charges_count": 1,
"charges_limit": 1,
"status": "active",
"cancel_at_period_end": true,
"cancellations": [
{}
],
"discounts": [
{}
],
"addons": [
{}
],
"items": [
{}
],
"last_payment_at": "2023-04-23T00:45:00.000000Z",
"unpaid": false,
"cancellation_requested": false,
"cancelled_at": null,
"reactivated_at": null,
"switched_at": null,
"previous_subscription_id": null,
"auto_collecting": true,
"metadata": [
{}
],
"tags": [
"tags"
],
"tags_meta": [],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
},
"customer_id": 1,
"customer": {
"id": 8435732,
"user_id": 5512,
"first_name": "John",
"last_name": "Smith",
"email": "test@test.com",
"marketing_consent": false,
"tos_consent_at": "2022-04-01T00:00:00.000000Z",
"external_id": "crm-8842",
"default_payment_method_id": 1,
"default_payment_method": {},
"payment_methods": [
{}
],
"subscriptions": [
{}
],
"past_due_invoice_count": 0,
"balance": 1500,
"tags": [
"VIP"
],
"tags_meta": [],
"notes": [
{}
],
"addresses": [
{}
],
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z"
},
"payment_method_id": 1,
"payment_method": {
"id": 567,
"type": "card",
"identifier": "4242",
"currencies": [
"USD",
"EUR"
],
"card": {
"last_four": "4242",
"expiry_month": "2",
"expiry_year": "2099",
"type": "credit",
"brand": "visa"
},
"ideal": {
"bank": "ING",
"bic": "INGBNL2A",
"email": "test@subbly.co",
"name": "John Doe"
},
"bancontact": {
"email": "test@subbly.co",
"name": "John Doe"
},
"acss_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "Royal Bank of Canada",
"transit_number": "12345",
"institution_number": "123",
"last_four": "6789"
},
"us_bank_account": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "US Bank",
"last4": "6789",
"routing_number": "123456789",
"account_type": "checking",
"account_holder_type": "individual"
},
"sepa_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"iban_last4": "6789",
"bank_code": "123456",
"country": "DE",
"branch_code": "12345"
},
"sofort": {
"email": "test@subbly.co",
"name": "John Doe",
"country": "DE"
},
"link": {
"email": "test@subbly.co",
"name": "John Doe"
},
"cashapp": {
"email": "test@subbly.co",
"name": "John Doe",
"buyer_id": "cashapp:123456789",
"cash_tag": "$subbly"
},
"created_at": "2022-04-01T00:00:00.000000Z"
},
"billing_address_id": 1,
"billing_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_address_id": 1,
"shipping_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_method_id": 1,
"shipping_method": {},
"currency_code": "USD",
"total": 1,
"sub_total": 1,
"adjustment": 1,
"discounts_amount": 1,
"tax_amount": 1,
"application_fee": 1,
"description": "description",
"first_shipment_at": "2022-04-01T00:00:00.000000Z",
"period_start": "2022-04-01T00:00:00.000000Z",
"period_end": "2022-04-01T00:00:00.000000Z",
"next_attempt_at": "2022-04-01T00:00:00.000000Z",
"paid_at": "2022-04-01T00:00:00.000000Z",
"voided_at": "2022-04-01T00:00:00.000000Z",
"status": "paid",
"items": [
{
"id": 1,
"product_id": 1,
"product": {},
"subscription_id": "subscription_id",
"addon_id": 1,
"subscription_item_id": 1,
"type": "subscription",
"description": "description",
"amount": 1,
"survey": {
"survey_id": 1,
"version": 2,
"data": [
{}
]
},
"bundle": {},
"quantity": 1,
"digital": true,
"tax_amount": 1,
"tax_rate": 1,
"tax_inclusive": true,
"discount_amount": 0,
"gift_card": {
"customer_email": "customer_email",
"customer_name": "customer_name",
"message": "message"
},
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"discounts": [
{
"id": 1,
"discount_id": 1,
"gift_card_id": 1,
"coupon_id": 1,
"coupon": {},
"type": "coupon",
"description": "description",
"amount": 1,
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"metadata": [
{
"id": 1,
"name": "Color",
"slug": "color-red",
"description": "description",
"unit": "kg",
"data_type": "single_line_string",
"preset": true,
"multiple": true,
"variant": true,
"access_level": "storefront",
"save_behavior": "customer",
"editable": true,
"values": [
{}
]
}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
]
}A detailed description of the invoice.
Path parameters
invoice_idRequiredintegerInvoice ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
ReturnsInvoice
Invoice object response
Error responses
400objectThe invoice exists but belongs to another shop.
404objectNo invoice exists with this ID.
422objectThe expand[] parameter is not an array.
curl https://api.subbly.co/private/v1/invoices/{invoice_id} \
-H 'X-API-KEY: <api-key>'{
"id": 1,
"subscription_id": 1,
"subscription": {
"id": 1,
"customer_id": 1,
"customer": {},
"referred_by": 1,
"product_id": 1,
"product": {},
"quantity": 1,
"shipping_address_id": 1,
"shipping_address": {},
"shipping_method_id": 1,
"shipping_method": {},
"shipping_carrier_id": 1,
"shipping_carrier_service": "shipping_carrier_service",
"billing_address_id": 1,
"billing_address": {},
"payment_method_id": 1,
"payment_method": {},
"currency_code": "USD",
"survey": {},
"preferences": {},
"bundle": {},
"gift": {
"message": "message",
"starts_at": "2022-02-24T04:00:00.000000Z",
"order_limit": 1
},
"commitment_term_total_payments": 1,
"cancel_at_end_of_commitment": true,
"next_payment_date": "2023-04-23T00:45:00.000000Z",
"starts_at": "2023-04-23T00:45:00.000000Z",
"active": true,
"paused": false,
"paused_at": null,
"skipping_until": null,
"waiting_until": null,
"past_due": false,
"successful_charges_count": 1,
"charges_limit": 1,
"status": "active",
"cancel_at_period_end": true,
"cancellations": [
{}
],
"discounts": [
{}
],
"addons": [
{}
],
"items": [
{}
],
"last_payment_at": "2023-04-23T00:45:00.000000Z",
"unpaid": false,
"cancellation_requested": false,
"cancelled_at": null,
"reactivated_at": null,
"switched_at": null,
"previous_subscription_id": null,
"auto_collecting": true,
"metadata": [
{}
],
"tags": [
"tags"
],
"tags_meta": [],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
},
"customer_id": 1,
"customer": {
"id": 8435732,
"user_id": 5512,
"first_name": "John",
"last_name": "Smith",
"email": "test@test.com",
"marketing_consent": false,
"tos_consent_at": "2022-04-01T00:00:00.000000Z",
"external_id": "crm-8842",
"default_payment_method_id": 1,
"default_payment_method": {},
"payment_methods": [
{}
],
"subscriptions": [
{}
],
"past_due_invoice_count": 0,
"balance": 1500,
"tags": [
"VIP"
],
"tags_meta": [],
"notes": [
{}
],
"addresses": [
{}
],
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z"
},
"payment_method_id": 1,
"payment_method": {
"id": 567,
"type": "card",
"identifier": "4242",
"currencies": [
"USD",
"EUR"
],
"card": {
"last_four": "4242",
"expiry_month": "2",
"expiry_year": "2099",
"type": "credit",
"brand": "visa"
},
"ideal": {
"bank": "ING",
"bic": "INGBNL2A",
"email": "test@subbly.co",
"name": "John Doe"
},
"bancontact": {
"email": "test@subbly.co",
"name": "John Doe"
},
"acss_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "Royal Bank of Canada",
"transit_number": "12345",
"institution_number": "123",
"last_four": "6789"
},
"us_bank_account": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "US Bank",
"last4": "6789",
"routing_number": "123456789",
"account_type": "checking",
"account_holder_type": "individual"
},
"sepa_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"iban_last4": "6789",
"bank_code": "123456",
"country": "DE",
"branch_code": "12345"
},
"sofort": {
"email": "test@subbly.co",
"name": "John Doe",
"country": "DE"
},
"link": {
"email": "test@subbly.co",
"name": "John Doe"
},
"cashapp": {
"email": "test@subbly.co",
"name": "John Doe",
"buyer_id": "cashapp:123456789",
"cash_tag": "$subbly"
},
"created_at": "2022-04-01T00:00:00.000000Z"
},
"billing_address_id": 1,
"billing_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_address_id": 1,
"shipping_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_method_id": 1,
"shipping_method": {},
"currency_code": "USD",
"total": 1,
"sub_total": 1,
"adjustment": 1,
"discounts_amount": 1,
"tax_amount": 1,
"application_fee": 1,
"description": "description",
"first_shipment_at": "2022-04-01T00:00:00.000000Z",
"period_start": "2022-04-01T00:00:00.000000Z",
"period_end": "2022-04-01T00:00:00.000000Z",
"next_attempt_at": "2022-04-01T00:00:00.000000Z",
"paid_at": "2022-04-01T00:00:00.000000Z",
"voided_at": "2022-04-01T00:00:00.000000Z",
"status": "paid",
"items": [
{
"id": 1,
"product_id": 1,
"product": {},
"subscription_id": "subscription_id",
"addon_id": 1,
"subscription_item_id": 1,
"type": "subscription",
"description": "description",
"amount": 1,
"survey": {
"survey_id": 1,
"version": 2,
"data": [
{}
]
},
"bundle": {},
"quantity": 1,
"digital": true,
"tax_amount": 1,
"tax_rate": 1,
"tax_inclusive": true,
"discount_amount": 0,
"gift_card": {
"customer_email": "customer_email",
"customer_name": "customer_name",
"message": "message"
},
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"discounts": [
{
"id": 1,
"discount_id": 1,
"gift_card_id": 1,
"coupon_id": 1,
"coupon": {},
"type": "coupon",
"description": "description",
"amount": 1,
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"metadata": [
{
"id": 1,
"name": "Color",
"slug": "color-red",
"description": "description",
"unit": "kg",
"data_type": "single_line_string",
"preset": true,
"multiple": true,
"variant": true,
"access_level": "storefront",
"save_behavior": "customer",
"editable": true,
"values": [
{}
]
}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}Schedule the next payment for current invoice
Path parameters
invoice_idRequiredstringInvoice ID
Request body
Schedule Payment Body
next_attempt_atRequiredstringReturnsInvoice
Invoice object response
Error responses
400objectThe invoice is not in open or past_due status.
curl -X PATCH https://api.subbly.co/private/v1/invoices/{invoice_id}/schedule_payment \
-H 'X-API-KEY: <api-key>' \
-H 'Content-Type: application/json' \
-d '{
"next_attempt_at": "2022-02-24T04:00:00"
}'{
"id": 1,
"subscription_id": 1,
"subscription": {
"id": 1,
"customer_id": 1,
"customer": {},
"referred_by": 1,
"product_id": 1,
"product": {},
"quantity": 1,
"shipping_address_id": 1,
"shipping_address": {},
"shipping_method_id": 1,
"shipping_method": {},
"shipping_carrier_id": 1,
"shipping_carrier_service": "shipping_carrier_service",
"billing_address_id": 1,
"billing_address": {},
"payment_method_id": 1,
"payment_method": {},
"currency_code": "USD",
"survey": {},
"preferences": {},
"bundle": {},
"gift": {
"message": "message",
"starts_at": "2022-02-24T04:00:00.000000Z",
"order_limit": 1
},
"commitment_term_total_payments": 1,
"cancel_at_end_of_commitment": true,
"next_payment_date": "2023-04-23T00:45:00.000000Z",
"starts_at": "2023-04-23T00:45:00.000000Z",
"active": true,
"paused": false,
"paused_at": null,
"skipping_until": null,
"waiting_until": null,
"past_due": false,
"successful_charges_count": 1,
"charges_limit": 1,
"status": "active",
"cancel_at_period_end": true,
"cancellations": [
{}
],
"discounts": [
{}
],
"addons": [
{}
],
"items": [
{}
],
"last_payment_at": "2023-04-23T00:45:00.000000Z",
"unpaid": false,
"cancellation_requested": false,
"cancelled_at": null,
"reactivated_at": null,
"switched_at": null,
"previous_subscription_id": null,
"auto_collecting": true,
"metadata": [
{}
],
"tags": [
"tags"
],
"tags_meta": [],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
},
"customer_id": 1,
"customer": {
"id": 8435732,
"user_id": 5512,
"first_name": "John",
"last_name": "Smith",
"email": "test@test.com",
"marketing_consent": false,
"tos_consent_at": "2022-04-01T00:00:00.000000Z",
"external_id": "crm-8842",
"default_payment_method_id": 1,
"default_payment_method": {},
"payment_methods": [
{}
],
"subscriptions": [
{}
],
"past_due_invoice_count": 0,
"balance": 1500,
"tags": [
"VIP"
],
"tags_meta": [],
"notes": [
{}
],
"addresses": [
{}
],
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z"
},
"payment_method_id": 1,
"payment_method": {
"id": 567,
"type": "card",
"identifier": "4242",
"currencies": [
"USD",
"EUR"
],
"card": {
"last_four": "4242",
"expiry_month": "2",
"expiry_year": "2099",
"type": "credit",
"brand": "visa"
},
"ideal": {
"bank": "ING",
"bic": "INGBNL2A",
"email": "test@subbly.co",
"name": "John Doe"
},
"bancontact": {
"email": "test@subbly.co",
"name": "John Doe"
},
"acss_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "Royal Bank of Canada",
"transit_number": "12345",
"institution_number": "123",
"last_four": "6789"
},
"us_bank_account": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "US Bank",
"last4": "6789",
"routing_number": "123456789",
"account_type": "checking",
"account_holder_type": "individual"
},
"sepa_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"iban_last4": "6789",
"bank_code": "123456",
"country": "DE",
"branch_code": "12345"
},
"sofort": {
"email": "test@subbly.co",
"name": "John Doe",
"country": "DE"
},
"link": {
"email": "test@subbly.co",
"name": "John Doe"
},
"cashapp": {
"email": "test@subbly.co",
"name": "John Doe",
"buyer_id": "cashapp:123456789",
"cash_tag": "$subbly"
},
"created_at": "2022-04-01T00:00:00.000000Z"
},
"billing_address_id": 1,
"billing_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_address_id": 1,
"shipping_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_method_id": 1,
"shipping_method": {},
"currency_code": "USD",
"total": 1,
"sub_total": 1,
"adjustment": 1,
"discounts_amount": 1,
"tax_amount": 1,
"application_fee": 1,
"description": "description",
"first_shipment_at": "2022-04-01T00:00:00.000000Z",
"period_start": "2022-04-01T00:00:00.000000Z",
"period_end": "2022-04-01T00:00:00.000000Z",
"next_attempt_at": "2022-04-01T00:00:00.000000Z",
"paid_at": "2022-04-01T00:00:00.000000Z",
"voided_at": "2022-04-01T00:00:00.000000Z",
"status": "paid",
"items": [
{
"id": 1,
"product_id": 1,
"product": {},
"subscription_id": "subscription_id",
"addon_id": 1,
"subscription_item_id": 1,
"type": "subscription",
"description": "description",
"amount": 1,
"survey": {
"survey_id": 1,
"version": 2,
"data": [
{}
]
},
"bundle": {},
"quantity": 1,
"digital": true,
"tax_amount": 1,
"tax_rate": 1,
"tax_inclusive": true,
"discount_amount": 0,
"gift_card": {
"customer_email": "customer_email",
"customer_name": "customer_name",
"message": "message"
},
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"discounts": [
{
"id": 1,
"discount_id": 1,
"gift_card_id": 1,
"coupon_id": 1,
"coupon": {},
"type": "coupon",
"description": "description",
"amount": 1,
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"metadata": [
{
"id": 1,
"name": "Color",
"slug": "color-red",
"description": "description",
"unit": "kg",
"data_type": "single_line_string",
"preset": true,
"multiple": true,
"variant": true,
"access_level": "storefront",
"save_behavior": "customer",
"editable": true,
"values": [
{}
]
}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}Void an open or past_due invoice. Sets the status to voided, records voided_at and cancels the pending payment validation attempt. The related subscription is not changed. The invoice must not have a processing payment intent.
Path parameters
invoice_idRequiredintegerInvoice ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
ReturnsInvoice
Invoice object response
Error responses
400objectThe invoice is not in open or past_due status (invoice_status_not_allowed), or it has a processing payment intent (bad_request).
404objectInvoice not found
curl -X POST https://api.subbly.co/private/v1/invoices/{invoice_id}/void \
-H 'X-API-KEY: <api-key>'{
"id": 1,
"subscription_id": 1,
"subscription": {
"id": 1,
"customer_id": 1,
"customer": {},
"referred_by": 1,
"product_id": 1,
"product": {},
"quantity": 1,
"shipping_address_id": 1,
"shipping_address": {},
"shipping_method_id": 1,
"shipping_method": {},
"shipping_carrier_id": 1,
"shipping_carrier_service": "shipping_carrier_service",
"billing_address_id": 1,
"billing_address": {},
"payment_method_id": 1,
"payment_method": {},
"currency_code": "USD",
"survey": {},
"preferences": {},
"bundle": {},
"gift": {
"message": "message",
"starts_at": "2022-02-24T04:00:00.000000Z",
"order_limit": 1
},
"commitment_term_total_payments": 1,
"cancel_at_end_of_commitment": true,
"next_payment_date": "2023-04-23T00:45:00.000000Z",
"starts_at": "2023-04-23T00:45:00.000000Z",
"active": true,
"paused": false,
"paused_at": null,
"skipping_until": null,
"waiting_until": null,
"past_due": false,
"successful_charges_count": 1,
"charges_limit": 1,
"status": "active",
"cancel_at_period_end": true,
"cancellations": [
{}
],
"discounts": [
{}
],
"addons": [
{}
],
"items": [
{}
],
"last_payment_at": "2023-04-23T00:45:00.000000Z",
"unpaid": false,
"cancellation_requested": false,
"cancelled_at": null,
"reactivated_at": null,
"switched_at": null,
"previous_subscription_id": null,
"auto_collecting": true,
"metadata": [
{}
],
"tags": [
"tags"
],
"tags_meta": [],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
},
"customer_id": 1,
"customer": {
"id": 8435732,
"user_id": 5512,
"first_name": "John",
"last_name": "Smith",
"email": "test@test.com",
"marketing_consent": false,
"tos_consent_at": "2022-04-01T00:00:00.000000Z",
"external_id": "crm-8842",
"default_payment_method_id": 1,
"default_payment_method": {},
"payment_methods": [
{}
],
"subscriptions": [
{}
],
"past_due_invoice_count": 0,
"balance": 1500,
"tags": [
"VIP"
],
"tags_meta": [],
"notes": [
{}
],
"addresses": [
{}
],
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z"
},
"payment_method_id": 1,
"payment_method": {
"id": 567,
"type": "card",
"identifier": "4242",
"currencies": [
"USD",
"EUR"
],
"card": {
"last_four": "4242",
"expiry_month": "2",
"expiry_year": "2099",
"type": "credit",
"brand": "visa"
},
"ideal": {
"bank": "ING",
"bic": "INGBNL2A",
"email": "test@subbly.co",
"name": "John Doe"
},
"bancontact": {
"email": "test@subbly.co",
"name": "John Doe"
},
"acss_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "Royal Bank of Canada",
"transit_number": "12345",
"institution_number": "123",
"last_four": "6789"
},
"us_bank_account": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "US Bank",
"last4": "6789",
"routing_number": "123456789",
"account_type": "checking",
"account_holder_type": "individual"
},
"sepa_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"iban_last4": "6789",
"bank_code": "123456",
"country": "DE",
"branch_code": "12345"
},
"sofort": {
"email": "test@subbly.co",
"name": "John Doe",
"country": "DE"
},
"link": {
"email": "test@subbly.co",
"name": "John Doe"
},
"cashapp": {
"email": "test@subbly.co",
"name": "John Doe",
"buyer_id": "cashapp:123456789",
"cash_tag": "$subbly"
},
"created_at": "2022-04-01T00:00:00.000000Z"
},
"billing_address_id": 1,
"billing_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_address_id": 1,
"shipping_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_method_id": 1,
"shipping_method": {},
"currency_code": "USD",
"total": 1,
"sub_total": 1,
"adjustment": 1,
"discounts_amount": 1,
"tax_amount": 1,
"application_fee": 1,
"description": "description",
"first_shipment_at": "2022-04-01T00:00:00.000000Z",
"period_start": "2022-04-01T00:00:00.000000Z",
"period_end": "2022-04-01T00:00:00.000000Z",
"next_attempt_at": "2022-04-01T00:00:00.000000Z",
"paid_at": "2022-04-01T00:00:00.000000Z",
"voided_at": "2022-04-01T00:00:00.000000Z",
"status": "paid",
"items": [
{
"id": 1,
"product_id": 1,
"product": {},
"subscription_id": "subscription_id",
"addon_id": 1,
"subscription_item_id": 1,
"type": "subscription",
"description": "description",
"amount": 1,
"survey": {
"survey_id": 1,
"version": 2,
"data": [
{}
]
},
"bundle": {},
"quantity": 1,
"digital": true,
"tax_amount": 1,
"tax_rate": 1,
"tax_inclusive": true,
"discount_amount": 0,
"gift_card": {
"customer_email": "customer_email",
"customer_name": "customer_name",
"message": "message"
},
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"discounts": [
{
"id": 1,
"discount_id": 1,
"gift_card_id": 1,
"coupon_id": 1,
"coupon": {},
"type": "coupon",
"description": "description",
"amount": 1,
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"metadata": [
{
"id": 1,
"name": "Color",
"slug": "color-red",
"description": "description",
"unit": "kg",
"data_type": "single_line_string",
"preset": true,
"multiple": true,
"variant": true,
"access_level": "storefront",
"save_behavior": "customer",
"editable": true,
"values": [
{}
]
}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}Forgive an open or past_due invoice. Voids the invoice the same way as the void endpoint (sets the status to voided, records voided_at and cancels the pending payment validation attempt) and additionally clears the related subscription's past-due state. The invoice must belong to a subscription and must not have a processing payment intent.
Path parameters
invoice_idRequiredintegerInvoice ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
ReturnsInvoice
Invoice object response
Error responses
400objectThe invoice is not in open or past_due status (invoice_status_not_allowed), does not belong to a subscription, or it has a processing payment intent (bad_request).
404objectInvoice not found
curl -X POST https://api.subbly.co/private/v1/invoices/{invoice_id}/forgive \
-H 'X-API-KEY: <api-key>'{
"id": 1,
"subscription_id": 1,
"subscription": {
"id": 1,
"customer_id": 1,
"customer": {},
"referred_by": 1,
"product_id": 1,
"product": {},
"quantity": 1,
"shipping_address_id": 1,
"shipping_address": {},
"shipping_method_id": 1,
"shipping_method": {},
"shipping_carrier_id": 1,
"shipping_carrier_service": "shipping_carrier_service",
"billing_address_id": 1,
"billing_address": {},
"payment_method_id": 1,
"payment_method": {},
"currency_code": "USD",
"survey": {},
"preferences": {},
"bundle": {},
"gift": {
"message": "message",
"starts_at": "2022-02-24T04:00:00.000000Z",
"order_limit": 1
},
"commitment_term_total_payments": 1,
"cancel_at_end_of_commitment": true,
"next_payment_date": "2023-04-23T00:45:00.000000Z",
"starts_at": "2023-04-23T00:45:00.000000Z",
"active": true,
"paused": false,
"paused_at": null,
"skipping_until": null,
"waiting_until": null,
"past_due": false,
"successful_charges_count": 1,
"charges_limit": 1,
"status": "active",
"cancel_at_period_end": true,
"cancellations": [
{}
],
"discounts": [
{}
],
"addons": [
{}
],
"items": [
{}
],
"last_payment_at": "2023-04-23T00:45:00.000000Z",
"unpaid": false,
"cancellation_requested": false,
"cancelled_at": null,
"reactivated_at": null,
"switched_at": null,
"previous_subscription_id": null,
"auto_collecting": true,
"metadata": [
{}
],
"tags": [
"tags"
],
"tags_meta": [],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
},
"customer_id": 1,
"customer": {
"id": 8435732,
"user_id": 5512,
"first_name": "John",
"last_name": "Smith",
"email": "test@test.com",
"marketing_consent": false,
"tos_consent_at": "2022-04-01T00:00:00.000000Z",
"external_id": "crm-8842",
"default_payment_method_id": 1,
"default_payment_method": {},
"payment_methods": [
{}
],
"subscriptions": [
{}
],
"past_due_invoice_count": 0,
"balance": 1500,
"tags": [
"VIP"
],
"tags_meta": [],
"notes": [
{}
],
"addresses": [
{}
],
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z"
},
"payment_method_id": 1,
"payment_method": {
"id": 567,
"type": "card",
"identifier": "4242",
"currencies": [
"USD",
"EUR"
],
"card": {
"last_four": "4242",
"expiry_month": "2",
"expiry_year": "2099",
"type": "credit",
"brand": "visa"
},
"ideal": {
"bank": "ING",
"bic": "INGBNL2A",
"email": "test@subbly.co",
"name": "John Doe"
},
"bancontact": {
"email": "test@subbly.co",
"name": "John Doe"
},
"acss_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "Royal Bank of Canada",
"transit_number": "12345",
"institution_number": "123",
"last_four": "6789"
},
"us_bank_account": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "US Bank",
"last4": "6789",
"routing_number": "123456789",
"account_type": "checking",
"account_holder_type": "individual"
},
"sepa_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"iban_last4": "6789",
"bank_code": "123456",
"country": "DE",
"branch_code": "12345"
},
"sofort": {
"email": "test@subbly.co",
"name": "John Doe",
"country": "DE"
},
"link": {
"email": "test@subbly.co",
"name": "John Doe"
},
"cashapp": {
"email": "test@subbly.co",
"name": "John Doe",
"buyer_id": "cashapp:123456789",
"cash_tag": "$subbly"
},
"created_at": "2022-04-01T00:00:00.000000Z"
},
"billing_address_id": 1,
"billing_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_address_id": 1,
"shipping_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_method_id": 1,
"shipping_method": {},
"currency_code": "USD",
"total": 1,
"sub_total": 1,
"adjustment": 1,
"discounts_amount": 1,
"tax_amount": 1,
"application_fee": 1,
"description": "description",
"first_shipment_at": "2022-04-01T00:00:00.000000Z",
"period_start": "2022-04-01T00:00:00.000000Z",
"period_end": "2022-04-01T00:00:00.000000Z",
"next_attempt_at": "2022-04-01T00:00:00.000000Z",
"paid_at": "2022-04-01T00:00:00.000000Z",
"voided_at": "2022-04-01T00:00:00.000000Z",
"status": "paid",
"items": [
{
"id": 1,
"product_id": 1,
"product": {},
"subscription_id": "subscription_id",
"addon_id": 1,
"subscription_item_id": 1,
"type": "subscription",
"description": "description",
"amount": 1,
"survey": {
"survey_id": 1,
"version": 2,
"data": [
{}
]
},
"bundle": {},
"quantity": 1,
"digital": true,
"tax_amount": 1,
"tax_rate": 1,
"tax_inclusive": true,
"discount_amount": 0,
"gift_card": {
"customer_email": "customer_email",
"customer_name": "customer_name",
"message": "message"
},
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"discounts": [
{
"id": 1,
"discount_id": 1,
"gift_card_id": 1,
"coupon_id": 1,
"coupon": {},
"type": "coupon",
"description": "description",
"amount": 1,
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"metadata": [
{
"id": 1,
"name": "Color",
"slug": "color-red",
"description": "description",
"unit": "kg",
"data_type": "single_line_string",
"preset": true,
"multiple": true,
"variant": true,
"access_level": "storefront",
"save_behavior": "customer",
"editable": true,
"values": [
{}
]
}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}Record a successful payment for an open or past_due invoice without charging the customer. Creates a success charge transaction, marks the invoice as paid (records paid_at) and updates the related subscription's payment state. The invoice must belong to a subscription and must not have a processing payment intent.
Path parameters
invoice_idRequiredintegerInvoice ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
ReturnsInvoice
Invoice object response
Error responses
400objectThe invoice is not in open or past_due status (invoice_status_not_allowed), does not belong to a subscription, or it has a processing payment intent (bad_request).
404objectInvoice not found
curl -X POST https://api.subbly.co/private/v1/invoices/{invoice_id}/mark_as_paid \
-H 'X-API-KEY: <api-key>'{
"id": 1,
"subscription_id": 1,
"subscription": {
"id": 1,
"customer_id": 1,
"customer": {},
"referred_by": 1,
"product_id": 1,
"product": {},
"quantity": 1,
"shipping_address_id": 1,
"shipping_address": {},
"shipping_method_id": 1,
"shipping_method": {},
"shipping_carrier_id": 1,
"shipping_carrier_service": "shipping_carrier_service",
"billing_address_id": 1,
"billing_address": {},
"payment_method_id": 1,
"payment_method": {},
"currency_code": "USD",
"survey": {},
"preferences": {},
"bundle": {},
"gift": {
"message": "message",
"starts_at": "2022-02-24T04:00:00.000000Z",
"order_limit": 1
},
"commitment_term_total_payments": 1,
"cancel_at_end_of_commitment": true,
"next_payment_date": "2023-04-23T00:45:00.000000Z",
"starts_at": "2023-04-23T00:45:00.000000Z",
"active": true,
"paused": false,
"paused_at": null,
"skipping_until": null,
"waiting_until": null,
"past_due": false,
"successful_charges_count": 1,
"charges_limit": 1,
"status": "active",
"cancel_at_period_end": true,
"cancellations": [
{}
],
"discounts": [
{}
],
"addons": [
{}
],
"items": [
{}
],
"last_payment_at": "2023-04-23T00:45:00.000000Z",
"unpaid": false,
"cancellation_requested": false,
"cancelled_at": null,
"reactivated_at": null,
"switched_at": null,
"previous_subscription_id": null,
"auto_collecting": true,
"metadata": [
{}
],
"tags": [
"tags"
],
"tags_meta": [],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
},
"customer_id": 1,
"customer": {
"id": 8435732,
"user_id": 5512,
"first_name": "John",
"last_name": "Smith",
"email": "test@test.com",
"marketing_consent": false,
"tos_consent_at": "2022-04-01T00:00:00.000000Z",
"external_id": "crm-8842",
"default_payment_method_id": 1,
"default_payment_method": {},
"payment_methods": [
{}
],
"subscriptions": [
{}
],
"past_due_invoice_count": 0,
"balance": 1500,
"tags": [
"VIP"
],
"tags_meta": [],
"notes": [
{}
],
"addresses": [
{}
],
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z"
},
"payment_method_id": 1,
"payment_method": {
"id": 567,
"type": "card",
"identifier": "4242",
"currencies": [
"USD",
"EUR"
],
"card": {
"last_four": "4242",
"expiry_month": "2",
"expiry_year": "2099",
"type": "credit",
"brand": "visa"
},
"ideal": {
"bank": "ING",
"bic": "INGBNL2A",
"email": "test@subbly.co",
"name": "John Doe"
},
"bancontact": {
"email": "test@subbly.co",
"name": "John Doe"
},
"acss_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "Royal Bank of Canada",
"transit_number": "12345",
"institution_number": "123",
"last_four": "6789"
},
"us_bank_account": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "US Bank",
"last4": "6789",
"routing_number": "123456789",
"account_type": "checking",
"account_holder_type": "individual"
},
"sepa_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"iban_last4": "6789",
"bank_code": "123456",
"country": "DE",
"branch_code": "12345"
},
"sofort": {
"email": "test@subbly.co",
"name": "John Doe",
"country": "DE"
},
"link": {
"email": "test@subbly.co",
"name": "John Doe"
},
"cashapp": {
"email": "test@subbly.co",
"name": "John Doe",
"buyer_id": "cashapp:123456789",
"cash_tag": "$subbly"
},
"created_at": "2022-04-01T00:00:00.000000Z"
},
"billing_address_id": 1,
"billing_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_address_id": 1,
"shipping_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"shipping_method_id": 1,
"shipping_method": {},
"currency_code": "USD",
"total": 1,
"sub_total": 1,
"adjustment": 1,
"discounts_amount": 1,
"tax_amount": 1,
"application_fee": 1,
"description": "description",
"first_shipment_at": "2022-04-01T00:00:00.000000Z",
"period_start": "2022-04-01T00:00:00.000000Z",
"period_end": "2022-04-01T00:00:00.000000Z",
"next_attempt_at": "2022-04-01T00:00:00.000000Z",
"paid_at": "2022-04-01T00:00:00.000000Z",
"voided_at": "2022-04-01T00:00:00.000000Z",
"status": "paid",
"items": [
{
"id": 1,
"product_id": 1,
"product": {},
"subscription_id": "subscription_id",
"addon_id": 1,
"subscription_item_id": 1,
"type": "subscription",
"description": "description",
"amount": 1,
"survey": {
"survey_id": 1,
"version": 2,
"data": [
{}
]
},
"bundle": {},
"quantity": 1,
"digital": true,
"tax_amount": 1,
"tax_rate": 1,
"tax_inclusive": true,
"discount_amount": 0,
"gift_card": {
"customer_email": "customer_email",
"customer_name": "customer_name",
"message": "message"
},
"metadata": [
{}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"discounts": [
{
"id": 1,
"discount_id": 1,
"gift_card_id": 1,
"coupon_id": 1,
"coupon": {},
"type": "coupon",
"description": "description",
"amount": 1,
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}
],
"metadata": [
{
"id": 1,
"name": "Color",
"slug": "color-red",
"description": "description",
"unit": "kg",
"data_type": "single_line_string",
"preset": true,
"multiple": true,
"variant": true,
"access_level": "storefront",
"save_behavior": "customer",
"editable": true,
"values": [
{}
]
}
],
"created_at": "2022-04-01T00:00:00.000000Z",
"updated_at": "2022-04-01T00:00:00.000000Z"
}