recurly package

Submodules

recurly.base_client module

class recurly.base_client.BaseClient(api_key)

Bases: object

recurly.base_client.request_converter(value)

Used by json serializer to cast values

recurly.base_errors module

exception recurly.base_errors.ApiError(message, error)

Bases: recurly.base_errors.RecurlyError

exception recurly.base_errors.NetworkError

Bases: recurly.base_errors.RecurlyError

exception recurly.base_errors.RecurlyError

Bases: Exception

classmethod error_from_status(status)

recurly.client module

class recurly.client.Client(api_key)

Bases: recurly.base_client.BaseClient

api_version()
cancel_subscription(subscription_id, **options)

Cancel a subscription

Parameters

subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Keyword Arguments

body (SubscriptionCancel) – The body of the request.

Returns

A canceled or failed subscription.

Return type

Subscription

collect_invoice(invoice_id, **options)

Collect a pending or past due, automatic invoice

Parameters

invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

Keyword Arguments

body (InvoiceCollect) – The body of the request.

Returns

The updated invoice.

Return type

Invoice

convert_trial(subscription_id)

Convert trial subscription

Parameters

subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Returns

A subscription.

Return type

Subscription

create_account(body)

Create an account

Parameters

body (dict) – The request body. It should follow the schema of AccountCreate.

Returns

An account.

Return type

Account

create_billing_info(account_id, body)

Set an account’s billing information when the wallet feature is enabled

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • body (dict) – The request body. It should follow the schema of BillingInfoCreate.

Returns

Updated billing information.

Return type

BillingInfo

create_coupon(body)

Create a new coupon

Parameters

body (dict) – The request body. It should follow the schema of CouponCreate.

Returns

A new coupon.

Return type

Coupon

create_coupon_redemption(account_id, body)

Generate an active coupon redemption on an account

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • body (dict) – The request body. It should follow the schema of CouponRedemptionCreate.

Returns

Returns the new coupon redemption.

Return type

CouponRedemption

create_invoice(account_id, body)

Create an invoice for pending line items

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • body (dict) – The request body. It should follow the schema of InvoiceCreate.

Returns

Returns the new invoices.

Return type

InvoiceCollection

create_item(body)

Create a new item

Parameters

body (dict) – The request body. It should follow the schema of ItemCreate.

Returns

A new item.

Return type

Item

create_line_item(account_id, body)

Create a new line item for the account

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • body (dict) – The request body. It should follow the schema of LineItemCreate.

Returns

Returns the new line item.

Return type

LineItem

create_measured_unit(body)

Create a new measured unit

Parameters

body (dict) – The request body. It should follow the schema of MeasuredUnitCreate.

Returns

A new measured unit.

Return type

MeasuredUnit

create_plan(body)

Create a plan

Parameters

body (dict) – The request body. It should follow the schema of PlanCreate.

Returns

A plan.

Return type

Plan

create_plan_add_on(plan_id, body)

Create an add-on

Parameters
  • plan_id (str) – Plan ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

  • body (dict) – The request body. It should follow the schema of AddOnCreate.

Returns

An add-on.

Return type

AddOn

create_purchase(body)

Create a new purchase

Parameters

body (dict) – The request body. It should follow the schema of PurchaseCreate.

Returns

Returns the new invoices

Return type

InvoiceCollection

create_shipping_address(account_id, body)

Create a new shipping address for the account

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • body (dict) – The request body. It should follow the schema of ShippingAddressCreate.

Returns

Returns the new shipping address.

Return type

ShippingAddress

create_shipping_method(body)

Create a new shipping method

Parameters

body (dict) – The request body. It should follow the schema of ShippingMethodCreate.

Returns

A new shipping method.

Return type

ShippingMethod

create_subscription(body)

Create a new subscription

Parameters

body (dict) – The request body. It should follow the schema of SubscriptionCreate.

Returns

A subscription.

Return type

Subscription

create_subscription_change(subscription_id, body)

Create a new subscription change

Parameters
  • subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

  • body (dict) – The request body. It should follow the schema of SubscriptionChangeCreate.

Returns

A subscription change.

Return type

SubscriptionChange

create_usage(subscription_id, add_on_id, body)

Log a usage record on this subscription add-on

Parameters
  • subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

  • add_on_id (str) – Add-on ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

  • body (dict) – The request body. It should follow the schema of UsageCreate.

Returns

The created usage record.

Return type

Usage

deactivate_account(account_id)

Deactivate an account

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Returns

An account.

Return type

Account

deactivate_coupon(coupon_id)

Expire a coupon

Parameters

coupon_id (str) – Coupon ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-10off.

Returns

The expired Coupon

Return type

Coupon

deactivate_item(item_id)

Deactivate an item

Parameters

item_id (str) – Item ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-red.

Returns

An item.

Return type

Item

deactivate_shipping_method(shipping_method_id)

Deactivate a shipping method

Parameters

shipping_method_id (str) – Shipping Method ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-usps_2-day.

Returns

A shipping method.

Return type

ShippingMethod

deactivate_unique_coupon_code(unique_coupon_code_id)

Deactivate a unique coupon code

Parameters

unique_coupon_code_id (str) – Unique Coupon Code ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-abc-8dh2-def.

Returns

A unique coupon code.

Return type

UniqueCouponCode

fail_invoice(invoice_id)

Mark an open invoice as failed

Parameters

invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

Returns

The updated invoice.

Return type

Invoice

get_a_billing_info(account_id, billing_info_id)

Fetch a billing info

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • billing_info_id (str) – Billing Info ID.

Returns

A billing info.

Return type

BillingInfo

get_account(account_id)

Fetch an account

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Returns

An account.

Return type

Account

get_account_acquisition(account_id)

Fetch an account’s acquisition data

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Returns

An account’s acquisition data.

Return type

AccountAcquisition

get_account_balance(account_id)

Fetch an account’s balance and past due status

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Returns

An account’s balance.

Return type

AccountBalance

get_account_note(account_id, account_note_id)

Fetch an account note

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • account_note_id (str) – Account Note ID.

Returns

An account note.

Return type

AccountNote

get_active_coupon_redemption(account_id)

Show the coupon redemption that is active on an account

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Returns

An active coupon redemption on an account.

Return type

CouponRedemption

get_add_on(add_on_id)

Fetch an add-on

Parameters

add_on_id (str) – Add-on ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

Returns

An add-on.

Return type

AddOn

get_billing_info(account_id)

Fetch an account’s billing information

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Returns

An account’s billing information.

Return type

BillingInfo

get_coupon(coupon_id)

Fetch a coupon

Parameters

coupon_id (str) – Coupon ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-10off.

Returns

A coupon.

Return type

Coupon

get_credit_payment(credit_payment_id)

Fetch a credit payment

Parameters

credit_payment_id (str) – Credit Payment ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Returns

A credit payment.

Return type

CreditPayment

get_custom_field_definition(custom_field_definition_id)

Fetch an custom field definition

Parameters

custom_field_definition_id (str) – Custom Field Definition ID

Returns

An custom field definition.

Return type

CustomFieldDefinition

get_export_dates()

List the dates that have an available export to download.

Returns

Returns a list of dates.

Return type

ExportDates

get_export_files(export_date)

List of the export files that are available to download.

Parameters

export_date (str) – Date for which to get a list of available automated export files. Date must be in YYYY-MM-DD format.

Returns

Returns a list of export files to download.

Return type

ExportFiles

get_invoice(invoice_id)

Fetch an invoice

Parameters

invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

Returns

An invoice.

Return type

Invoice

get_invoice_pdf(invoice_id)

Fetch an invoice as a PDF

Parameters

invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

Returns

An invoice as a PDF.

Return type

BinaryFile

get_item(item_id)

Fetch an item

Parameters

item_id (str) – Item ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-red.

Returns

An item.

Return type

Item

get_line_item(line_item_id)

Fetch a line item

Parameters

line_item_id (str) – Line Item ID.

Returns

A line item.

Return type

LineItem

get_measured_unit(measured_unit_id)

Fetch a measured unit

Parameters

measured_unit_id (str) – Measured unit ID or name. For ID no prefix is used e.g. e28zov4fw0v2. For name use prefix name-, e.g. name-Storage.

Returns

An item.

Return type

MeasuredUnit

get_plan(plan_id)

Fetch a plan

Parameters

plan_id (str) – Plan ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

Returns

A plan.

Return type

Plan

get_plan_add_on(plan_id, add_on_id)

Fetch a plan’s add-on

Parameters
  • plan_id (str) – Plan ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

  • add_on_id (str) – Add-on ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

Returns

An add-on.

Return type

AddOn

get_shipping_address(account_id, shipping_address_id)

Fetch an account’s shipping address

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • shipping_address_id (str) – Shipping Address ID.

Returns

A shipping address.

Return type

ShippingAddress

get_shipping_method(id)

Fetch a shipping method

Parameters

id (str) – Shipping Method ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-usps_2-day.

Returns

A shipping method.

Return type

ShippingMethod

get_site(site_id)

Fetch a site

Parameters

site_id (str) – Site ID or subdomain. For ID no prefix is used e.g. e28zov4fw0v2. For subdomain use prefix subdomain-, e.g. subdomain-recurly.

Returns

A site.

Return type

Site

get_subscription(subscription_id)

Fetch a subscription

Parameters

subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Returns

A subscription.

Return type

Subscription

get_subscription_change(subscription_id)

Fetch a subscription’s pending change

Parameters

subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Returns

A subscription’s pending change.

Return type

SubscriptionChange

get_transaction(transaction_id)

Fetch a transaction

Parameters

transaction_id (str) – Transaction ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Returns

A transaction.

Return type

Transaction

get_unique_coupon_code(unique_coupon_code_id)

Fetch a unique coupon code

Parameters

unique_coupon_code_id (str) – Unique Coupon Code ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-abc-8dh2-def.

Returns

A unique coupon code.

Return type

UniqueCouponCode

get_usage(usage_id)

Get a usage record

Parameters

usage_id (str) – Usage Record ID.

Returns

The usage record.

Return type

Usage

list_account_acquisition(**options)

List a site’s account acquisition data

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

Returns

A list of the site’s account acquisition data.

Return type

Pager

list_account_coupon_redemptions(account_id, **options)

Show the coupon redemptions for an account

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

Returns

A list of the the coupon redemptions on an account.

Return type

Pager

list_account_credit_payments(account_id, **options)

List an account’s credit payments

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Keyword Arguments
  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

Returns

A list of the account’s credit payments.

Return type

Pager

list_account_invoices(account_id, **options)

List an account’s invoices

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • type (str) – Filter by type when: - type=charge, only charge invoices will be returned. - type=credit, only credit invoices will be returned. - type=non-legacy, only charge and credit invoices will be returned. - type=legacy, only legacy invoices will be returned.

Returns

A list of the account’s invoices.

Return type

Pager

list_account_line_items(account_id, **options)

List an account’s line items

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • original (str) – Filter by original field.

  • state (str) – Filter by state field.

  • type (str) – Filter by type field.

Returns

A list of the account’s line items.

Return type

Pager

list_account_notes(account_id, **options)

Fetch a list of an account’s notes

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Keyword Arguments

ids (list of str) –

Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

Important notes:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

Returns

A list of an account’s notes.

Return type

Pager

list_account_subscriptions(account_id, **options)

List an account’s subscriptions

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • state (str) –

    Filter by state.

    • When state=active, state=canceled, state=expired, or state=future, subscriptions with states that match the query and only those subscriptions will be returned.

    • When state=in_trial, only subscriptions that have a trial_started_at date earlier than now and a trial_ends_at date later than now will be returned.

    • When state=live, only subscriptions that are in an active, canceled, or future state or are in trial will be returned.

Returns

A list of the account’s subscriptions.

Return type

Pager

list_account_transactions(account_id, **options)

List an account’s transactions

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • type (str) – Filter by type field. The value payment will return both purchase and capture transactions.

  • success (str) – Filter by success field.

Returns

A list of the account’s transactions.

Return type

Pager

list_accounts(**options)

List a site’s accounts

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • email (str) – Filter for accounts with this exact email address. A blank value will return accounts with both null and “” email addresses. Note that multiple accounts can share one email address.

  • subscriber (bool) – Filter for accounts with or without a subscription in the active, canceled, or future state.

  • past_due (str) – Filter for accounts with an invoice in the past_due state.

Returns

A list of the site’s accounts.

Return type

Pager

list_add_ons(**options)

List a site’s add-ons

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • state (str) – Filter by state.

Returns

A list of add-ons.

Return type

Pager

list_billing_infos(account_id, **options)

Get the list of billing information associated with an account

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

Returns

A list of the the billing information for an account’s

Return type

Pager

list_child_accounts(account_id, **options)

List an account’s child accounts

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • email (str) – Filter for accounts with this exact email address. A blank value will return accounts with both null and “” email addresses. Note that multiple accounts can share one email address.

  • subscriber (bool) – Filter for accounts with or without a subscription in the active, canceled, or future state.

  • past_due (str) – Filter for accounts with an invoice in the past_due state.

Returns

A list of an account’s child accounts.

Return type

Pager

list_coupons(**options)

List a site’s coupons

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

Returns

A list of the site’s coupons.

Return type

Pager

list_credit_payments(**options)

List a site’s credit payments

Keyword Arguments
  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

Returns

A list of the site’s credit payments.

Return type

Pager

list_custom_field_definitions(**options)

List a site’s custom field definitions

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • related_type (str) – Filter by related type.

Returns

A list of the site’s custom field definitions.

Return type

Pager

list_invoice_coupon_redemptions(invoice_id, **options)

Show the coupon redemptions applied to an invoice

Parameters

invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

Returns

A list of the the coupon redemptions associated with the invoice.

Return type

Pager

list_invoice_line_items(invoice_id, **options)

List an invoice’s line items

Parameters

invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • original (str) – Filter by original field.

  • state (str) – Filter by state field.

  • type (str) – Filter by type field.

Returns

A list of the invoice’s line items.

Return type

Pager

list_invoices(**options)

List a site’s invoices

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • type (str) – Filter by type when: - type=charge, only charge invoices will be returned. - type=credit, only credit invoices will be returned. - type=non-legacy, only charge and credit invoices will be returned. - type=legacy, only legacy invoices will be returned.

Returns

A list of the site’s invoices.

Return type

Pager

list_items(**options)

List a site’s items

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • state (str) – Filter by state.

Returns

A list of the site’s items.

Return type

Pager

list_line_items(**options)

List a site’s line items

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • original (str) – Filter by original field.

  • state (str) – Filter by state field.

  • type (str) – Filter by type field.

Returns

A list of the site’s line items.

Return type

Pager

list_measured_unit(**options)

List a site’s measured units

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • state (str) – Filter by state.

Returns

A list of the site’s measured units.

Return type

Pager

list_plan_add_ons(plan_id, **options)

List a plan’s add-ons

Parameters

plan_id (str) – Plan ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • state (str) – Filter by state.

Returns

A list of add-ons.

Return type

Pager

list_plans(**options)

List a site’s plans

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • state (str) – Filter by state.

Returns

A list of plans.

Return type

Pager

List an invoice’s related credit or charge invoices

Parameters

invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

Returns

A list of the credit or charge invoices associated with the invoice.

Return type

Pager

list_shipping_addresses(account_id, **options)

Fetch a list of an account’s shipping addresses

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

Returns

A list of an account’s shipping addresses.

Return type

Pager

list_shipping_methods(**options)

List a site’s shipping methods

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

Returns

A list of the site’s shipping methods.

Return type

Pager

list_sites(**options)

List sites

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • state (str) – Filter by state.

Returns

A list of sites.

Return type

Pager

list_subscription_coupon_redemptions(subscription_id, **options)

Show the coupon redemptions for a subscription

Parameters

subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

Returns

A list of the the coupon redemptions on a subscription.

Return type

Pager

list_subscription_invoices(subscription_id, **options)

List a subscription’s invoices

Parameters

subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • type (str) – Filter by type when: - type=charge, only charge invoices will be returned. - type=credit, only credit invoices will be returned. - type=non-legacy, only charge and credit invoices will be returned. - type=legacy, only legacy invoices will be returned.

Returns

A list of the subscription’s invoices.

Return type

Pager

list_subscription_line_items(subscription_id, **options)

List a subscription’s line items

Parameters

subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • original (str) – Filter by original field.

  • state (str) – Filter by state field.

  • type (str) – Filter by type field.

Returns

A list of the subscription’s line items.

Return type

Pager

list_subscriptions(**options)

List a site’s subscriptions

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • state (str) –

    Filter by state.

    • When state=active, state=canceled, state=expired, or state=future, subscriptions with states that match the query and only those subscriptions will be returned.

    • When state=in_trial, only subscriptions that have a trial_started_at date earlier than now and a trial_ends_at date later than now will be returned.

    • When state=live, only subscriptions that are in an active, canceled, or future state or are in trial will be returned.

Returns

A list of the site’s subscriptions.

Return type

Pager

list_transactions(**options)

List a site’s transactions

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • type (str) – Filter by type field. The value payment will return both purchase and capture transactions.

  • success (str) – Filter by success field.

Returns

A list of the site’s transactions.

Return type

Pager

list_unique_coupon_codes(coupon_id, **options)

List unique coupon codes associated with a bulk coupon

Parameters

coupon_id (str) – Coupon ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-10off.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by updated_at in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=created_at or sort=updated_at. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

Returns

A list of unique coupon codes that were generated

Return type

Pager

list_usage(subscription_id, add_on_id, **options)

List a subscription add-on’s usage records

Parameters
  • subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

  • add_on_id (str) – Add-on ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

Keyword Arguments
  • ids (list of str) –

    Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6.

    Important notes:

    • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)

    • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.

    • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

  • limit (int) – Limit number of records 1-200.

  • order (str) – Sort order.

  • sort (str) – Sort field. You really only want to sort by usage_timestamp in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

  • begin_time (datetime) – Inclusively filter by begin_time when sort=usage_timestamp or sort=recorded_timestamp. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • end_time (datetime) – Inclusively filter by end_time when sort=usage_timestamp or sort=recorded_timestamp. Note: this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

  • billing_status (str) – Filter by usage record’s billing status

Returns

A list of the subscription add-on’s usage records.

Return type

Pager

mark_invoice_successful(invoice_id)

Mark an open invoice as successful

Parameters

invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

Returns

The updated invoice.

Return type

Invoice

modify_subscription(subscription_id, body)

Modify a subscription

Parameters
  • subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

  • body (dict) – The request body. It should follow the schema of SubscriptionUpdate.

Returns

A subscription.

Return type

Subscription

pause_subscription(subscription_id, body)

Pause subscription

Parameters
  • subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

  • body (dict) – The request body. It should follow the schema of SubscriptionPause.

Returns

A subscription.

Return type

Subscription

preview_invoice(account_id, body)

Preview new invoice for pending line items

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • body (dict) – The request body. It should follow the schema of InvoiceCreate.

Returns

Returns the invoice previews.

Return type

InvoiceCollection

preview_purchase(body)

Preview a new purchase

Parameters

body (dict) – The request body. It should follow the schema of PurchaseCreate.

Returns

Returns preview of the new invoices

Return type

InvoiceCollection

preview_subscription_change(subscription_id, body)

Preview a new subscription change

Parameters
  • subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

  • body (dict) – The request body. It should follow the schema of SubscriptionChangeCreate.

Returns

A subscription change.

Return type

SubscriptionChangePreview

put_invoice(invoice_id, body)

Update an invoice

Parameters
  • invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

  • body (dict) – The request body. It should follow the schema of InvoiceUpdatable.

Returns

An invoice.

Return type

Invoice

reactivate_account(account_id)

Reactivate an inactive account

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Returns

An account.

Return type

Account

reactivate_item(item_id)

Reactivate an inactive item

Parameters

item_id (str) – Item ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-red.

Returns

An item.

Return type

Item

reactivate_subscription(subscription_id)

Reactivate a canceled subscription

Parameters

subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Returns

An active subscription.

Return type

Subscription

reactivate_unique_coupon_code(unique_coupon_code_id)

Restore a unique coupon code

Parameters

unique_coupon_code_id (str) – Unique Coupon Code ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-abc-8dh2-def.

Returns

A unique coupon code.

Return type

UniqueCouponCode

record_external_transaction(invoice_id, body)

Record an external payment for a manual invoices.

Parameters
  • invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

  • body (dict) – The request body. It should follow the schema of ExternalTransaction.

Returns

The recorded transaction.

Return type

Transaction

refund_invoice(invoice_id, body)

Refund an invoice

Parameters
  • invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

  • body (dict) – The request body. It should follow the schema of InvoiceRefund.

Returns

Returns the new credit invoice.

Return type

Invoice

remove_a_billing_info(account_id, billing_info_id)

Remove an account’s billing information

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • billing_info_id (str) – Billing Info ID.

Returns

Billing information deleted

Return type

Empty

remove_account_acquisition(account_id)

Remove an account’s acquisition data

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Returns

Acquisition data was succesfully deleted.

Return type

Empty

remove_billing_info(account_id)

Remove an account’s billing information

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Returns

Billing information deleted

Return type

Empty

remove_coupon_redemption(account_id)

Delete the active coupon redemption from an account

Parameters

account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

Returns

Coupon redemption deleted.

Return type

CouponRedemption

remove_line_item(line_item_id)

Delete an uninvoiced line item

Parameters

line_item_id (str) – Line Item ID.

Returns

Line item deleted.

Return type

Empty

remove_measured_unit(measured_unit_id)

Remove a measured unit

Parameters

measured_unit_id (str) – Measured unit ID or name. For ID no prefix is used e.g. e28zov4fw0v2. For name use prefix name-, e.g. name-Storage.

Returns

A measured unit.

Return type

MeasuredUnit

remove_plan(plan_id)

Remove a plan

Parameters

plan_id (str) – Plan ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

Returns

Plan deleted

Return type

Plan

remove_plan_add_on(plan_id, add_on_id)

Remove an add-on

Parameters
  • plan_id (str) – Plan ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

  • add_on_id (str) – Add-on ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

Returns

Add-on deleted

Return type

AddOn

remove_shipping_address(account_id, shipping_address_id)

Remove an account’s shipping address

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • shipping_address_id (str) – Shipping Address ID.

Returns

Shipping address deleted.

Return type

Empty

remove_subscription_change(subscription_id)

Delete the pending subscription change

Parameters

subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Returns

Subscription change was deleted.

Return type

Empty

remove_usage(usage_id)

Delete a usage record.

Parameters

usage_id (str) – Usage Record ID.

Returns

Usage was successfully deleted.

Return type

Empty

reopen_invoice(invoice_id)

Reopen a closed, manual invoice

Parameters

invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

Returns

The updated invoice.

Return type

Invoice

restore_coupon(coupon_id, body)

Restore an inactive coupon

Parameters
  • coupon_id (str) – Coupon ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-10off.

  • body (dict) – The request body. It should follow the schema of CouponUpdate.

Returns

The restored coupon.

Return type

Coupon

resume_subscription(subscription_id)

Resume subscription

Parameters

subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Returns

A subscription.

Return type

Subscription

terminate_subscription(subscription_id, **options)

Terminate a subscription

Parameters

subscription_id (str) – Subscription ID or UUID. For ID no prefix is used e.g. e28zov4fw0v2. For UUID use prefix uuid-, e.g. uuid-123457890.

Keyword Arguments

refund (str) –

The type of refund to perform:

  • full - Performs a full refund of the last invoice for the current subscription term.

  • partial - Prorates a refund based on the amount of time remaining in the current bill cycle.

  • none - Terminates the subscription without a refund.

In the event that the most recent invoice is a $0 invoice paid entirely by credit, Recurly will apply the credit back to the customer’s account.

You may also terminate a subscription with no refund and then manually refund specific invoices.

Returns

An expired subscription.

Return type

Subscription

update_a_billing_info(account_id, billing_info_id, body)

Update an account’s billing information

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • billing_info_id (str) – Billing Info ID.

  • body (dict) – The request body. It should follow the schema of BillingInfoCreate.

Returns

Updated billing information.

Return type

BillingInfo

update_account(account_id, body)

Modify an account

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • body (dict) – The request body. It should follow the schema of AccountUpdate.

Returns

An account.

Return type

Account

update_account_acquisition(account_id, body)

Update an account’s acquisition data

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • body (dict) – The request body. It should follow the schema of AccountAcquisitionUpdatable.

Returns

An account’s updated acquisition data.

Return type

AccountAcquisition

update_billing_info(account_id, body)

Set an account’s billing information

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • body (dict) – The request body. It should follow the schema of BillingInfoCreate.

Returns

Updated billing information.

Return type

BillingInfo

update_coupon(coupon_id, body)

Update an active coupon

Parameters
  • coupon_id (str) – Coupon ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-10off.

  • body (dict) – The request body. It should follow the schema of CouponUpdate.

Returns

The updated coupon.

Return type

Coupon

update_item(item_id, body)

Update an active item

Parameters
  • item_id (str) – Item ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-red.

  • body (dict) – The request body. It should follow the schema of ItemUpdate.

Returns

The updated item.

Return type

Item

update_measured_unit(measured_unit_id, body)

Update a measured unit

Parameters
  • measured_unit_id (str) – Measured unit ID or name. For ID no prefix is used e.g. e28zov4fw0v2. For name use prefix name-, e.g. name-Storage.

  • body (dict) – The request body. It should follow the schema of MeasuredUnitUpdate.

Returns

The updated measured_unit.

Return type

MeasuredUnit

update_plan(plan_id, body)

Update a plan

Parameters
  • plan_id (str) – Plan ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

  • body (dict) – The request body. It should follow the schema of PlanUpdate.

Returns

A plan.

Return type

Plan

update_plan_add_on(plan_id, add_on_id, body)

Update an add-on

Parameters
  • plan_id (str) – Plan ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

  • add_on_id (str) – Add-on ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-gold.

  • body (dict) – The request body. It should follow the schema of AddOnUpdate.

Returns

An add-on.

Return type

AddOn

update_shipping_address(account_id, shipping_address_id, body)

Update an account’s shipping address

Parameters
  • account_id (str) – Account ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-bob.

  • shipping_address_id (str) – Shipping Address ID.

  • body (dict) – The request body. It should follow the schema of ShippingAddressUpdate.

Returns

The updated shipping address.

Return type

ShippingAddress

update_shipping_method(shipping_method_id, body)

Update an active Shipping Method

Parameters
  • shipping_method_id (str) – Shipping Method ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For code use prefix code-, e.g. code-usps_2-day.

  • body (dict) – The request body. It should follow the schema of ShippingMethodUpdate.

Returns

The updated shipping method.

Return type

ShippingMethod

update_usage(usage_id, body)

Update a usage record

Parameters
  • usage_id (str) – Usage Record ID.

  • body (dict) – The request body. It should follow the schema of UsageCreate.

Returns

The updated usage record.

Return type

Usage

void_invoice(invoice_id)

Void a credit invoice.

Parameters

invoice_id (str) – Invoice ID or number. For ID no prefix is used e.g. e28zov4fw0v2. For number use prefix number-, e.g. number-1000.

Returns

The updated invoice.

Return type

Invoice

recurly.errors module

exception recurly.errors.BadGatewayError(message, error)

Bases: recurly.errors.ServerError

exception recurly.errors.BadRequestError(message, error)

Bases: recurly.errors.ClientError

exception recurly.errors.ClientError(message, error)

Bases: recurly.base_errors.ApiError

exception recurly.errors.ForbiddenError(message, error)

Bases: recurly.errors.ClientError

exception recurly.errors.ImmutableSubscriptionError(message, error)

Bases: recurly.errors.UnprocessableEntityError

exception recurly.errors.InternalServerError(message, error)

Bases: recurly.errors.ServerError

exception recurly.errors.InvalidApiKeyError(message, error)

Bases: recurly.errors.ForbiddenError

exception recurly.errors.InvalidApiVersionError(message, error)

Bases: recurly.errors.NotAcceptableError

exception recurly.errors.InvalidContentTypeError(message, error)

Bases: recurly.errors.BadRequestError

exception recurly.errors.InvalidPermissionsError(message, error)

Bases: recurly.errors.ForbiddenError

exception recurly.errors.InvalidTokenError(message, error)

Bases: recurly.errors.UnprocessableEntityError

exception recurly.errors.MissingFeatureError(message, error)

Bases: recurly.errors.UnprocessableEntityError

exception recurly.errors.NotAcceptableError(message, error)

Bases: recurly.errors.ClientError

exception recurly.errors.NotFoundError(message, error)

Bases: recurly.errors.ClientError

exception recurly.errors.NotModifiedError(message, error)

Bases: recurly.errors.ResponseError

exception recurly.errors.PaymentRequiredError(message, error)

Bases: recurly.errors.ClientError

exception recurly.errors.PreconditionFailedError(message, error)

Bases: recurly.errors.ClientError

exception recurly.errors.RateLimitedError(message, error)

Bases: recurly.errors.TooManyRequestsError

exception recurly.errors.RedirectionError(message, error)

Bases: recurly.errors.ResponseError

exception recurly.errors.ResponseError(message, error)

Bases: recurly.base_errors.ApiError

exception recurly.errors.ServerError(message, error)

Bases: recurly.errors.ResponseError

exception recurly.errors.ServiceNotAvailableError(message, error)

Bases: recurly.errors.InternalServerError

exception recurly.errors.ServiceUnavailableError(message, error)

Bases: recurly.errors.ServerError

exception recurly.errors.SimultaneousRequestError(message, error)

Bases: recurly.errors.UnprocessableEntityError

exception recurly.errors.TimeoutError(message, error)

Bases: recurly.errors.ServerError

exception recurly.errors.TooManyRequestsError(message, error)

Bases: recurly.errors.ClientError

exception recurly.errors.TransactionError(message, error)

Bases: recurly.errors.UnprocessableEntityError

exception recurly.errors.UnauthorizedError(message, error)

Bases: recurly.errors.ClientError

exception recurly.errors.UnavailableInApiVersionError(message, error)

Bases: recurly.errors.NotAcceptableError

exception recurly.errors.UnknownApiVersionError(message, error)

Bases: recurly.errors.NotAcceptableError

exception recurly.errors.UnprocessableEntityError(message, error)

Bases: recurly.errors.ClientError

exception recurly.errors.ValidationError(message, error)

Bases: recurly.errors.UnprocessableEntityError

recurly.pager module

class recurly.pager.ItemIterator(client, next_url, params)

Bases: object

class recurly.pager.PageIterator(client, next_url, params)

Bases: object

class recurly.pager.Pager(client, path, params)

Bases: object

count()

Makes a HEAD request to the API to determine how many total records exist.

first()

Performs a request with the pager limit set to 1 and only returns the first result in the response.

items()

An iterator that enumerates each item on the server and paginates under the hood.

pages()

An iterator that enumerates each page of results.

take(n)

Performs a request with the pager limit set to n and only returns the first n results in the response. n is limited to the maximum page size.

recurly.request module

class recurly.request.Request(method, path, body=None)

Bases: object

Class representing a request to Recurly

recurly.resource module

class recurly.resource.Empty

Bases: recurly.resource.Resource

A special resource that represents an empty response

class recurly.resource.Page(properties)

Bases: recurly.resource.Resource

A special resource that represents a single page of data

has_more

True if there is another page of data available

Type

bool

next

The relative path to the next page of data

Type

str

data

The list of data for this page. The data will be the requested type of Resource.

Type

list of Resource

class recurly.resource.Resource

Bases: object

Class representing a server-side object in Recurly

classmethod cast_error(response)
classmethod cast_file(response)
classmethod cast_json(properties, class_name=None, response=None)

Casts a dict of properties into a Recurly Resource

get_response()
Returns

The metadata about the response from the recurly server

Return type

Response

locator()

recurly.resources module

class recurly.resources.Account

Bases: recurly.resource.Resource

address
Type

Address

bill_to

An enumerable describing the billing behavior of the account, specifically whether the account is self-paying or will rely on the parent account to pay.

Type

str

billing_info
Type

BillingInfo

cc_emails

Additional email address that should receive account correspondence. These should be separated only by commas. These CC emails will receive all emails that the email field also receives.

Type

str

code

The unique identifier of the account. This cannot be changed once the account is created.

Type

str

company
Type

str

created_at

When the account was created.

Type

datetime

custom_fields

The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.

Type

list of CustomField

deleted_at

If present, when the account was last marked inactive.

Type

datetime

email

The email address used for communicating with this customer. The customer will also use this email address to log into your hosted account management pages. This value does not need to be unique.

Type

str

exemption_certificate

The tax exemption certificate number for the account. If the merchant has an integration for the Vertex tax provider, this optional value will be sent in any tax calculation requests for the account.

Type

str

first_name
Type

str

has_active_subscription

Indicates if the account has an active subscription.

Type

bool

has_canceled_subscription

Indicates if the account has a canceled subscription.

Type

bool

has_future_subscription

Indicates if the account has a future subscription.

Type

bool

has_live_subscription

Indicates if the account has a subscription that is either active, canceled, future, or paused.

Type

bool

has_past_due_invoice

Indicates if the account has a past due invoice.

Type

bool

has_paused_subscription

Indicates if the account has a paused subscription.

Type

bool

hosted_login_token

The unique token for automatically logging the account in to the hosted management pages. You may automatically log the user into their hosted management pages by directing the user to: https://{subdomain}.recurly.com/account/{hosted_login_token}.

Type

str

id
Type

str

last_name
Type

str

object

Object type

Type

str

parent_account_id

The UUID of the parent account associated with this account.

Type

str

preferred_locale

Used to determine the language and locale of emails sent on behalf of the merchant to the customer.

Type

str

shipping_addresses

The shipping addresses on the account.

Type

list of ShippingAddress

state

Accounts can be either active or inactive.

Type

str

tax_exempt

The tax status of the account. true exempts tax on the account, false applies tax on the account.

Type

bool

updated_at

When the account was last changed.

Type

datetime

username

A secondary value for the account.

Type

str

vat_number

The VAT number of the account (to avoid having the VAT applied). This is only used for manually collected invoices.

Type

str

schema = {'address': 'Address', 'bill_to': <class 'str'>, 'billing_info': 'BillingInfo', 'cc_emails': <class 'str'>, 'code': <class 'str'>, 'company': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'custom_fields': ['CustomField'], 'deleted_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'email': <class 'str'>, 'exemption_certificate': <class 'str'>, 'first_name': <class 'str'>, 'has_active_subscription': <class 'bool'>, 'has_canceled_subscription': <class 'bool'>, 'has_future_subscription': <class 'bool'>, 'has_live_subscription': <class 'bool'>, 'has_past_due_invoice': <class 'bool'>, 'has_paused_subscription': <class 'bool'>, 'hosted_login_token': <class 'str'>, 'id': <class 'str'>, 'last_name': <class 'str'>, 'object': <class 'str'>, 'parent_account_id': <class 'str'>, 'preferred_locale': <class 'str'>, 'shipping_addresses': ['ShippingAddress'], 'state': <class 'str'>, 'tax_exempt': <class 'bool'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'username': <class 'str'>, 'vat_number': <class 'str'>}
class recurly.resources.AccountAcquisition

Bases: recurly.resource.Resource

account

Account mini details

Type

AccountMini

campaign

An arbitrary identifier for the marketing campaign that led to the acquisition of this account.

Type

str

channel

The channel through which the account was acquired.

Type

str

cost

Account balance

Type

AccountAcquisitionCost

created_at

When the account acquisition data was created.

Type

datetime

id
Type

str

object

Object type

Type

str

subchannel

An arbitrary subchannel string representing a distinction/subcategory within a broader channel.

Type

str

updated_at

When the account acquisition data was last changed.

Type

datetime

schema = {'account': 'AccountMini', 'campaign': <class 'str'>, 'channel': <class 'str'>, 'cost': 'AccountAcquisitionCost', 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'id': <class 'str'>, 'object': <class 'str'>, 'subchannel': <class 'str'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.AccountAcquisitionCost

Bases: recurly.resource.Resource

amount

The amount of the corresponding currency used to acquire the account.

Type

float

currency

3-letter ISO 4217 currency code.

Type

str

schema = {'amount': <class 'float'>, 'currency': <class 'str'>}
class recurly.resources.AccountBalance

Bases: recurly.resource.Resource

account

Account mini details

Type

AccountMini

balances
Type

list of AccountBalanceAmount

object

Object type

Type

str

past_due
Type

bool

schema = {'account': 'AccountMini', 'balances': ['AccountBalanceAmount'], 'object': <class 'str'>, 'past_due': <class 'bool'>}
class recurly.resources.AccountBalanceAmount

Bases: recurly.resource.Resource

amount

Total amount the account is past due.

Type

float

currency

3-letter ISO 4217 currency code.

Type

str

schema = {'amount': <class 'float'>, 'currency': <class 'str'>}
class recurly.resources.AccountMini

Bases: recurly.resource.Resource

bill_to
Type

str

code

The unique identifier of the account.

Type

str

company
Type

str

email

The email address used for communicating with this customer.

Type

str

first_name
Type

str

id
Type

str

last_name
Type

str

object

Object type

Type

str

parent_account_id
Type

str

schema = {'bill_to': <class 'str'>, 'code': <class 'str'>, 'company': <class 'str'>, 'email': <class 'str'>, 'first_name': <class 'str'>, 'id': <class 'str'>, 'last_name': <class 'str'>, 'object': <class 'str'>, 'parent_account_id': <class 'str'>}
class recurly.resources.AccountNote

Bases: recurly.resource.Resource

account_id
Type

str

created_at
Type

datetime

id
Type

str

message
Type

str

object

Object type

Type

str

user
Type

User

schema = {'account_id': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'id': <class 'str'>, 'message': <class 'str'>, 'object': <class 'str'>, 'user': 'User'}
class recurly.resources.AddOn

Bases: recurly.resource.Resource

accounting_code

Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on’s code.

Type

str

add_on_type

Whether the add-on type is fixed, or usage-based.

Type

str

avalara_service_type

Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the add-on is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types.

Type

int

avalara_transaction_type

Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the add-on is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types.

Type

int

code

The unique identifier for the add-on within its plan.

Type

str

created_at

Created at

Type

datetime

currencies

Add-on pricing

Type

list of AddOnPricing

default_quantity

Default quantity for the hosted pages.

Type

int

deleted_at

Deleted at

Type

datetime

display_quantity

Determines if the quantity field is displayed on the hosted pages for the add-on.

Type

bool

external_sku

Optional, stock keeping unit to link the item to other inventory systems.

Type

str

id

Add-on ID

Type

str

item

Just the important parts.

Type

ItemMini

measured_unit_id

System-generated unique identifier for an measured unit associated with the add-on.

Type

str

name

Describes your add-on and will appear in subscribers’ invoices.

Type

str

object

Object type

Type

str

optional

Whether the add-on is optional for the customer to include in their purchase on the hosted payment page. If false, the add-on will be included when a subscription is created through the Recurly UI. However, the add-on will not be included when a subscription is created through the API.

Type

bool

plan_id

Plan ID

Type

str

revenue_schedule_type

When this add-on is invoiced, the line item will use this revenue schedule. If item_code/item_id is part of the request then revenue_schedule_type must be absent in the request as the value will be set from the item.

Type

str

state

Add-ons can be either active or inactive.

Type

str

tax_code

Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use unknown, physical, or digital.

Type

str

tier_type

The type of tiering used by the Add-on.

Type

str

tiers

Tiers

Type

list of Tier

updated_at

Last updated at

Type

datetime

usage_percentage

The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0.

Type

float

usage_type

Type of usage, returns usage type if add_on_type is usage.

Type

str

schema = {'accounting_code': <class 'str'>, 'add_on_type': <class 'str'>, 'avalara_service_type': <class 'int'>, 'avalara_transaction_type': <class 'int'>, 'code': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'currencies': ['AddOnPricing'], 'default_quantity': <class 'int'>, 'deleted_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'display_quantity': <class 'bool'>, 'external_sku': <class 'str'>, 'id': <class 'str'>, 'item': 'ItemMini', 'measured_unit_id': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>, 'optional': <class 'bool'>, 'plan_id': <class 'str'>, 'revenue_schedule_type': <class 'str'>, 'state': <class 'str'>, 'tax_code': <class 'str'>, 'tier_type': <class 'str'>, 'tiers': ['Tier'], 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'usage_percentage': <class 'float'>, 'usage_type': <class 'str'>}
class recurly.resources.AddOnMini

Bases: recurly.resource.Resource

accounting_code

Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on’s code.

Type

str

add_on_type

Whether the add-on type is fixed, or usage-based.

Type

str

code

The unique identifier for the add-on within its plan.

Type

str

external_sku

Optional, stock keeping unit to link the item to other inventory systems.

Type

str

id

Add-on ID

Type

str

item_id

Item ID

Type

str

measured_unit_id

System-generated unique identifier for an measured unit associated with the add-on.

Type

str

name

Describes your add-on and will appear in subscribers’ invoices.

Type

str

object

Object type

Type

str

usage_percentage

The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0.

Type

float

usage_type

Type of usage, returns usage type if add_on_type is usage.

Type

str

schema = {'accounting_code': <class 'str'>, 'add_on_type': <class 'str'>, 'code': <class 'str'>, 'external_sku': <class 'str'>, 'id': <class 'str'>, 'item_id': <class 'str'>, 'measured_unit_id': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>, 'usage_percentage': <class 'float'>, 'usage_type': <class 'str'>}
class recurly.resources.AddOnPricing

Bases: recurly.resource.Resource

currency

3-letter ISO 4217 currency code.

Type

str

unit_amount

Unit price

Type

float

schema = {'currency': <class 'str'>, 'unit_amount': <class 'float'>}
class recurly.resources.Address

Bases: recurly.resource.Resource

city

City

Type

str

country

Country, 2-letter ISO code.

Type

str

first_name

First name

Type

str

last_name

Last name

Type

str

phone

Phone number

Type

str

postal_code

Zip or postal code.

Type

str

region

State or province.

Type

str

street1

Street 1

Type

str

street2

Street 2

Type

str

schema = {'city': <class 'str'>, 'country': <class 'str'>, 'first_name': <class 'str'>, 'last_name': <class 'str'>, 'phone': <class 'str'>, 'postal_code': <class 'str'>, 'region': <class 'str'>, 'street1': <class 'str'>, 'street2': <class 'str'>}
class recurly.resources.BillingInfo

Bases: recurly.resource.Resource

account_id
Type

str

address
Type

Address

company
Type

str

created_at

When the billing information was created.

Type

datetime

first_name
Type

str

fraud

Most recent fraud result.

Type

FraudInfo

id
Type

str

last_name
Type

str

object

Object type

Type

str

payment_method
Type

PaymentMethod

primary_payment_method

The primary_payment_method indicator is used to designate the primary billing info on the account. The first billing info created on an account will always become primary. Adding additional billing infos provides the flexibility to mark another billing info as primary, or adding additional non-primary billing infos. This can be accomplished by passing the primary_payment_method indicator. When adding billing infos via the billing_info and /accounts endpoints, this value is not permitted, and will return an error if provided.

Type

bool

updated_at

When the billing information was last changed.

Type

datetime

updated_by
Type

BillingInfoUpdatedBy

valid
Type

bool

vat_number

Customer’s VAT number (to avoid having the VAT applied). This is only used for automatically collected invoices.

Type

str

schema = {'account_id': <class 'str'>, 'address': 'Address', 'company': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'first_name': <class 'str'>, 'fraud': 'FraudInfo', 'id': <class 'str'>, 'last_name': <class 'str'>, 'object': <class 'str'>, 'payment_method': 'PaymentMethod', 'primary_payment_method': <class 'bool'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'updated_by': 'BillingInfoUpdatedBy', 'valid': <class 'bool'>, 'vat_number': <class 'str'>}
class recurly.resources.BillingInfoUpdatedBy

Bases: recurly.resource.Resource

country

Country of IP address, if known by Recurly.

Type

str

ip

Customer’s IP address when updating their billing information.

Type

str

schema = {'country': <class 'str'>, 'ip': <class 'str'>}
class recurly.resources.BinaryFile

Bases: recurly.resource.Resource

data
Type

str

schema = {'data': <class 'str'>}
class recurly.resources.Coupon

Bases: recurly.resource.Resource

applies_to_all_items

The coupon is valid for all items if true. If false then items will list the applicable items.

Type

bool

applies_to_all_plans

The coupon is valid for all plans if true. If false then plans and plans_names will list the applicable plans.

Type

bool

applies_to_non_plan_charges

The coupon is valid for one-time, non-plan charges if true.

Type

bool

bulk_coupon_code

The Coupon code of the parent Bulk Coupon

Type

str

bulk_coupon_id

The Coupon ID of the parent Bulk Coupon

Type

str

code

The code the customer enters to redeem the coupon.

Type

str

coupon_type

Whether the coupon is “single_code” or “bulk”. Bulk coupons will require a unique_code_template and will generate unique codes through the /generate endpoint.

Type

str

created_at

Created at

Type

datetime

discount

Details of the discount a coupon applies. Will contain a type property and one of the following properties: percent, fixed, trial.

Type

CouponDiscount

duration
  • “single_use” coupons applies to the first invoice only.

  • “temporal” coupons will apply to invoices for the duration determined by the temporal_unit and temporal_amount attributes.

Type

str

expired_at

The date and time the coupon was expired early or reached its max_redemptions.

Type

datetime

free_trial_amount

Sets the duration of time the free_trial_unit is for.

Type

int

free_trial_unit

Description of the unit of time the coupon is for. Used with free_trial_amount to determine the duration of time the coupon is for.

Type

str

hosted_page_description

This description will show up when a customer redeems a coupon on your Hosted Payment Pages, or if you choose to show the description on your own checkout page.

Type

str

id

Coupon ID

Type

str

invoice_description

Description of the coupon on the invoice.

Type

str

items

A list of items for which this coupon applies. This will be null if applies_to_all_items=true.

Type

list of ItemMini

max_redemptions

A maximum number of redemptions for the coupon. The coupon will expire when it hits its maximum redemptions.

Type

int

max_redemptions_per_account

Redemptions per account is the number of times a specific account can redeem the coupon. Set redemptions per account to 1 if you want to keep customers from gaming the system and getting more than one discount from the coupon campaign.

Type

int

name

The internal name for the coupon.

Type

str

object

Object type

Type

str

plans

A list of plans for which this coupon applies. This will be null if applies_to_all_plans=true.

Type

list of PlanMini

plans_names

A list of plan names for which this coupon applies.

Type

list of str

redeem_by

The date and time the coupon will expire and can no longer be redeemed. Time is always 11:59:59, the end-of-day Pacific time.

Type

datetime

redeemed_at

The date and time the unique coupon code was redeemed. This is only present for bulk coupons.

Type

datetime

redemption_resource

Whether the discount is for all eligible charges on the account, or only a specific subscription.

Type

str

state

Indicates if the coupon is redeemable, and if it is not, why.

Type

str

temporal_amount

If duration is “temporal” than temporal_amount is an integer which is multiplied by temporal_unit to define the duration that the coupon will be applied to invoices for.

Type

int

temporal_unit

If duration is “temporal” than temporal_unit is multiplied by temporal_amount to define the duration that the coupon will be applied to invoices for.

Type

str

unique_code_template

On a bulk coupon, the template from which unique coupon codes are generated.

Type

str

unique_coupon_codes_count

When this number reaches max_redemptions the coupon will no longer be redeemable.

Type

int

updated_at

Last updated at

Type

datetime

schema = {'applies_to_all_items': <class 'bool'>, 'applies_to_all_plans': <class 'bool'>, 'applies_to_non_plan_charges': <class 'bool'>, 'bulk_coupon_code': <class 'str'>, 'bulk_coupon_id': <class 'str'>, 'code': <class 'str'>, 'coupon_type': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'discount': 'CouponDiscount', 'duration': <class 'str'>, 'expired_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'free_trial_amount': <class 'int'>, 'free_trial_unit': <class 'str'>, 'hosted_page_description': <class 'str'>, 'id': <class 'str'>, 'invoice_description': <class 'str'>, 'items': ['ItemMini'], 'max_redemptions': <class 'int'>, 'max_redemptions_per_account': <class 'int'>, 'name': <class 'str'>, 'object': <class 'str'>, 'plans': ['PlanMini'], 'plans_names': <class 'list'>, 'redeem_by': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'redeemed_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'redemption_resource': <class 'str'>, 'state': <class 'str'>, 'temporal_amount': <class 'int'>, 'temporal_unit': <class 'str'>, 'unique_code_template': <class 'str'>, 'unique_coupon_codes_count': <class 'int'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.CouponDiscount

Bases: recurly.resource.Resource

currencies

This is only present when type=fixed.

Type

list of CouponDiscountPricing

percent

This is only present when type=percent.

Type

int

trial

This is only present when type=free_trial.

Type

CouponDiscountTrial

type
Type

str

schema = {'currencies': ['CouponDiscountPricing'], 'percent': <class 'int'>, 'trial': 'CouponDiscountTrial', 'type': <class 'str'>}
class recurly.resources.CouponDiscountPricing

Bases: recurly.resource.Resource

amount

Value of the fixed discount that this coupon applies.

Type

float

currency

3-letter ISO 4217 currency code.

Type

str

schema = {'amount': <class 'float'>, 'currency': <class 'str'>}
class recurly.resources.CouponDiscountTrial

Bases: recurly.resource.Resource

length

Trial length measured in the units specified by the sibling unit property

Type

int

unit

Temporal unit of the free trial

Type

str

schema = {'length': <class 'int'>, 'unit': <class 'str'>}
class recurly.resources.CouponMini

Bases: recurly.resource.Resource

code

The code the customer enters to redeem the coupon.

Type

str

coupon_type

Whether the coupon is “single_code” or “bulk”. Bulk coupons will require a unique_code_template and will generate unique codes through the /generate endpoint.

Type

str

discount

Details of the discount a coupon applies. Will contain a type property and one of the following properties: percent, fixed, trial.

Type

CouponDiscount

expired_at

The date and time the coupon was expired early or reached its max_redemptions.

Type

datetime

id

Coupon ID

Type

str

name

The internal name for the coupon.

Type

str

object

Object type

Type

str

state

Indicates if the coupon is redeemable, and if it is not, why.

Type

str

schema = {'code': <class 'str'>, 'coupon_type': <class 'str'>, 'discount': 'CouponDiscount', 'expired_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'id': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>, 'state': <class 'str'>}
class recurly.resources.CouponRedemption

Bases: recurly.resource.Resource

account

The Account on which the coupon was applied.

Type

AccountMini

coupon
Type

Coupon

created_at

Created at

Type

datetime

currency

3-letter ISO 4217 currency code.

Type

str

discounted

The amount that was discounted upon the application of the coupon, formatted with the currency.

Type

float

id

Coupon Redemption ID

Type

str

object

Will always be coupon.

Type

str

removed_at

The date and time the redemption was removed from the account (un-redeemed).

Type

datetime

state

Coupon Redemption state

Type

str

updated_at

Last updated at

Type

datetime

schema = {'account': 'AccountMini', 'coupon': 'Coupon', 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'currency': <class 'str'>, 'discounted': <class 'float'>, 'id': <class 'str'>, 'object': <class 'str'>, 'removed_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'state': <class 'str'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.CouponRedemptionMini

Bases: recurly.resource.Resource

coupon
Type

CouponMini

created_at

Created at

Type

datetime

discounted

The amount that was discounted upon the application of the coupon, formatted with the currency.

Type

float

id

Coupon Redemption ID

Type

str

object

Will always be coupon.

Type

str

state

Invoice state

Type

str

schema = {'coupon': 'CouponMini', 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'discounted': <class 'float'>, 'id': <class 'str'>, 'object': <class 'str'>, 'state': <class 'str'>}
class recurly.resources.CreditPayment

Bases: recurly.resource.Resource

account

Account mini details

Type

AccountMini

action

The action for which the credit was created.

Type

str

amount

Total credit payment amount applied to the charge invoice.

Type

float

applied_to_invoice

Invoice mini details

Type

InvoiceMini

created_at

Created at

Type

datetime

currency

3-letter ISO 4217 currency code.

Type

str

id

Credit Payment ID

Type

str

object

Object type

Type

str

original_credit_payment_id

For credit payments with action refund, this is the credit payment that was refunded.

Type

str

original_invoice

Invoice mini details

Type

InvoiceMini

refund_transaction
Type

Transaction

updated_at

Last updated at

Type

datetime

uuid

The UUID is useful for matching data with the CSV exports and building URLs into Recurly’s UI.

Type

str

voided_at

Voided at

Type

datetime

schema = {'account': 'AccountMini', 'action': <class 'str'>, 'amount': <class 'float'>, 'applied_to_invoice': 'InvoiceMini', 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'currency': <class 'str'>, 'id': <class 'str'>, 'object': <class 'str'>, 'original_credit_payment_id': <class 'str'>, 'original_invoice': 'InvoiceMini', 'refund_transaction': 'Transaction', 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'uuid': <class 'str'>, 'voided_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.CustomField

Bases: recurly.resource.Resource

name

Fields must be created in the UI before values can be assigned to them.

Type

str

value

Any values that resemble a credit card number or security code (CVV/CVC) will be rejected.

Type

str

schema = {'name': <class 'str'>, 'value': <class 'str'>}
class recurly.resources.CustomFieldDefinition

Bases: recurly.resource.Resource

created_at

Created at

Type

datetime

deleted_at

Definitions are initially soft deleted, and once all the values are removed from the accouts or subscriptions, will be hard deleted an no longer visible.

Type

datetime

display_name

Used to label the field when viewing and editing the field in Recurly’s admin UI.

Type

str

id

Custom field definition ID

Type

str

name

Used by the API to identify the field or reading and writing. The name can only be used once per Recurly object type.

Type

str

object

Object type

Type

str

related_type

Related Recurly object type

Type

str

tooltip

Displayed as a tooltip when editing the field in the Recurly admin UI.

Type

str

updated_at

Last updated at

Type

datetime

user_access

The access control applied inside Recurly’s admin UI: - api_only - No one will be able to view or edit this field’s data via the admin UI. - read_only - Users with the Customers role will be able to view this field’s data via the admin UI, but

editing will only be available via the API.

  • write - Users with the Customers role will be able to view and edit this field’s data via the admin UI.

Type

str

schema = {'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'deleted_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'display_name': <class 'str'>, 'id': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>, 'related_type': <class 'str'>, 'tooltip': <class 'str'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'user_access': <class 'str'>}
class recurly.resources.Error

Bases: recurly.resource.Resource

message

Message

Type

str

params

Parameter specific errors

Type

list of dict

type

Type

Type

str

schema = {'message': <class 'str'>, 'params': <class 'list'>, 'type': <class 'str'>}
class recurly.resources.ErrorMayHaveTransaction

Bases: recurly.resource.Resource

message

Message

Type

str

params

Parameter specific errors

Type

list of dict

transaction_error

This is only included on errors with type=transaction.

Type

TransactionError

type

Type

Type

str

schema = {'message': <class 'str'>, 'params': <class 'list'>, 'transaction_error': 'TransactionError', 'type': <class 'str'>}
class recurly.resources.ExportDates

Bases: recurly.resource.Resource

dates

An array of dates that have available exports.

Type

list of str

object

Object type

Type

str

schema = {'dates': <class 'list'>, 'object': <class 'str'>}
class recurly.resources.ExportFile

Bases: recurly.resource.Resource

href

A presigned link to download the export file.

Type

str

md5sum

MD5 hash of the export file.

Type

str

name

Name of the export file.

Type

str

schema = {'href': <class 'str'>, 'md5sum': <class 'str'>, 'name': <class 'str'>}
class recurly.resources.ExportFiles

Bases: recurly.resource.Resource

files
Type

list of ExportFile

object

Object type

Type

str

schema = {'files': ['ExportFile'], 'object': <class 'str'>}
class recurly.resources.FraudInfo

Bases: recurly.resource.Resource

decision

Kount decision

Type

str

risk_rules_triggered

Kount rules

Type

dict

score

Kount score

Type

int

schema = {'decision': <class 'str'>, 'risk_rules_triggered': <class 'dict'>, 'score': <class 'int'>}
class recurly.resources.Invoice

Bases: recurly.resource.Resource

account

Account mini details

Type

AccountMini

address
Type

InvoiceAddress

balance

The outstanding balance remaining on this invoice.

Type

float

billing_info_id

The billing_info_id is the value that represents a specific billing info for an end customer. When billing_info_id is used to assign billing info to the subscription, all future billing events for the subscription will bill to the specified billing info.

Type

str

closed_at

Date invoice was marked paid or failed.

Type

datetime

collection_method

An automatic invoice means a corresponding transaction is run using the account’s billing information at the same time the invoice is created. Manual invoices are created without a corresponding transaction. The merchant must enter a manual payment transaction or have the customer pay the invoice with an automatic method, like credit card, PayPal, Amazon, or ACH bank payment.

Type

str

created_at

Created at

Type

datetime

credit_payments

Credit payments

Type

list of CreditPayment

currency

3-letter ISO 4217 currency code.

Type

str

customer_notes

This will default to the Customer Notes text specified on the Invoice Settings. Specify custom notes to add or override Customer Notes.

Type

str

discount

Total discounts applied to this invoice.

Type

float

due_at

Date invoice is due. This is the date the net terms are reached.

Type

datetime

id

Invoice ID

Type

str

line_items
Type

LineItemList

net_terms

Integer representing the number of days after an invoice’s creation that the invoice will become past due. If an invoice’s net terms are set to ‘0’, it is due ‘On Receipt’ and will become past due 24 hours after it’s created. If an invoice is due net 30, it will become past due at 31 days exactly.

Type

int

number

If VAT taxation and the Country Invoice Sequencing feature are enabled, invoices will have country-specific invoice numbers for invoices billed to EU countries (ex: FR1001). Non-EU invoices will continue to use the site-level invoice number sequence.

Type

str

object

Object type

Type

str

origin

The event that created the invoice.

Type

str

paid

The total amount of successful payments transaction on this invoice.

Type

float

po_number

For manual invoicing, this identifies the PO number associated with the subscription.

Type

str

previous_invoice_id

On refund invoices, this value will exist and show the invoice ID of the purchase invoice the refund was created from.

Type

str

refundable_amount

The refundable amount on a charge invoice. It will be null for all other invoices.

Type

float

shipping_address
Type

ShippingAddress

state

Invoice state

Type

str

subscription_ids

If the invoice is charging or refunding for one or more subscriptions, these are their IDs.

Type

list of str

subtotal

The summation of charges, discounts, and credits, before tax.

Type

float

tax

The total tax on this invoice.

Type

float

tax_info

Tax info

Type

TaxInfo

terms_and_conditions

This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes to add or override Terms and Conditions.

Type

str

total

The final total on this invoice. The summation of invoice charges, discounts, credits, and tax.

Type

float

transactions

Transactions

Type

list of Transaction

type

Invoices are either charge, credit, or legacy invoices.

Type

str

updated_at

Last updated at

Type

datetime

vat_number

VAT registration number for the customer on this invoice. This will come from the VAT Number field in the Billing Info or the Account Info depending on your tax settings and the invoice collection method.

Type

str

vat_reverse_charge_notes

VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription.

Type

str

schema = {'account': 'AccountMini', 'address': 'InvoiceAddress', 'balance': <class 'float'>, 'billing_info_id': <class 'str'>, 'closed_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'collection_method': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'credit_payments': ['CreditPayment'], 'currency': <class 'str'>, 'customer_notes': <class 'str'>, 'discount': <class 'float'>, 'due_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'id': <class 'str'>, 'line_items': 'LineItemList', 'net_terms': <class 'int'>, 'number': <class 'str'>, 'object': <class 'str'>, 'origin': <class 'str'>, 'paid': <class 'float'>, 'po_number': <class 'str'>, 'previous_invoice_id': <class 'str'>, 'refundable_amount': <class 'float'>, 'shipping_address': 'ShippingAddress', 'state': <class 'str'>, 'subscription_ids': <class 'list'>, 'subtotal': <class 'float'>, 'tax': <class 'float'>, 'tax_info': 'TaxInfo', 'terms_and_conditions': <class 'str'>, 'total': <class 'float'>, 'transactions': ['Transaction'], 'type': <class 'str'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'vat_number': <class 'str'>, 'vat_reverse_charge_notes': <class 'str'>}
class recurly.resources.InvoiceAddress

Bases: recurly.resource.Resource

city

City

Type

str

company

Company

Type

str

country

Country, 2-letter ISO code.

Type

str

first_name

First name

Type

str

last_name

Last name

Type

str

name_on_account

Name on account

Type

str

phone

Phone number

Type

str

postal_code

Zip or postal code.

Type

str

region

State or province.

Type

str

street1

Street 1

Type

str

street2

Street 2

Type

str

schema = {'city': <class 'str'>, 'company': <class 'str'>, 'country': <class 'str'>, 'first_name': <class 'str'>, 'last_name': <class 'str'>, 'name_on_account': <class 'str'>, 'phone': <class 'str'>, 'postal_code': <class 'str'>, 'region': <class 'str'>, 'street1': <class 'str'>, 'street2': <class 'str'>}
class recurly.resources.InvoiceCollection

Bases: recurly.resource.Resource

charge_invoice
Type

Invoice

credit_invoices

Credit invoices

Type

list of Invoice

object

Object type

Type

str

schema = {'charge_invoice': 'Invoice', 'credit_invoices': ['Invoice'], 'object': <class 'str'>}
class recurly.resources.InvoiceMini

Bases: recurly.resource.Resource

id

Invoice ID

Type

str

number

Invoice number

Type

str

object

Object type

Type

str

state

Invoice state

Type

str

type

Invoice type

Type

str

schema = {'id': <class 'str'>, 'number': <class 'str'>, 'object': <class 'str'>, 'state': <class 'str'>, 'type': <class 'str'>}
class recurly.resources.Item

Bases: recurly.resource.Resource

accounting_code

Accounting code for invoice line items.

Type

str

avalara_service_type

Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types.

Type

int

avalara_transaction_type

Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types.

Type

int

code

Unique code to identify the item.

Type

str

created_at

Created at

Type

datetime

currencies

Item Pricing

Type

list of Pricing

custom_fields

The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.

Type

list of CustomField

deleted_at

Deleted at

Type

datetime

description

Optional, description.

Type

str

external_sku

Optional, stock keeping unit to link the item to other inventory systems.

Type

str

id

Item ID

Type

str

name

This name describes your item and will appear on the invoice when it’s purchased on a one time basis.

Type

str

object

Object type

Type

str

revenue_schedule_type

Revenue schedule type

Type

str

state

The current state of the item.

Type

str

tax_code

Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use unknown, physical, or digital.

Type

str

tax_exempt

true exempts tax on the item, false applies tax on the item.

Type

bool

updated_at

Last updated at

Type

datetime

schema = {'accounting_code': <class 'str'>, 'avalara_service_type': <class 'int'>, 'avalara_transaction_type': <class 'int'>, 'code': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'currencies': ['Pricing'], 'custom_fields': ['CustomField'], 'deleted_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'description': <class 'str'>, 'external_sku': <class 'str'>, 'id': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>, 'revenue_schedule_type': <class 'str'>, 'state': <class 'str'>, 'tax_code': <class 'str'>, 'tax_exempt': <class 'bool'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.ItemMini

Bases: recurly.resource.Resource

code

Unique code to identify the item.

Type

str

description

Optional, description.

Type

str

id

Item ID

Type

str

name

This name describes your item and will appear on the invoice when it’s purchased on a one time basis.

Type

str

object

Object type

Type

str

state

The current state of the item.

Type

str

schema = {'code': <class 'str'>, 'description': <class 'str'>, 'id': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>, 'state': <class 'str'>}
class recurly.resources.LineItem

Bases: recurly.resource.Resource

account

Account mini details

Type

AccountMini

accounting_code

Internal accounting code to help you reconcile your revenue to the correct ledger. Line items created as part of a subscription invoice will use the plan or add-on’s accounting code, otherwise the value will only be present if you define an accounting code when creating the line item.

Type

str

add_on_code

If the line item is a charge or credit for an add-on, this is its code.

Type

str

add_on_id

If the line item is a charge or credit for an add-on this is its ID.

Type

str

amount

(quantity * unit_amount) - (discount + tax)

Type

float

avalara_service_type

Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the line item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types.

Type

int

avalara_transaction_type

Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the line item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types.

Type

int

created_at

When the line item was created.

Type

datetime

credit_applied

The amount of credit from this line item that was applied to the invoice.

Type

float

credit_reason_code

The reason the credit was given when line item is type=credit.

Type

str

currency

3-letter ISO 4217 currency code.

Type

str

description

Description that appears on the invoice. For subscription related items this will be filled in automatically.

Type

str

discount

The discount applied to the line item.

Type

float

end_date

If this date is provided, it indicates the end of a time range.

Type

datetime

external_sku

Optional Stock Keeping Unit assigned to an item. Available when the Credit Invoices and Subscription Billing Terms features are enabled.

Type

str

id

Line item ID

Type

str

invoice_id

Once the line item has been invoiced this will be the invoice’s ID.

Type

str

invoice_number

Once the line item has been invoiced this will be the invoice’s number. If VAT taxation and the Country Invoice Sequencing feature are enabled, invoices will have country-specific invoice numbers for invoices billed to EU countries (ex: FR1001). Non-EU invoices will continue to use the site-level invoice number sequence.

Type

str

item_code

Unique code to identify an item. Available when the Credit Invoices and Subscription Billing Terms features are enabled.

Type

str

item_id

System-generated unique identifier for an item. Available when the Credit Invoices and Subscription Billing Terms features are enabled.

Type

str

legacy_category

Category to describe the role of a line item on a legacy invoice: - “charges” refers to charges being billed for on this invoice. - “credits” refers to refund or proration credits. This portion of the invoice can be considered a credit memo. - “applied_credits” refers to previous credits applied to this invoice. See their original_line_item_id to determine where the credit first originated. - “carryforwards” can be ignored. They exist to consume any remaining credit balance. A new credit with the same amount will be created and placed back on the account.

Type

str

object

Object type

Type

str

origin

A credit created from an original charge will have the value of the charge’s origin.

Type

str

original_line_item_invoice_id

The invoice where the credit originated. Will only have a value if the line item is a credit created from a previous credit, or if the credit was created from a charge refund.

Type

str

plan_code

If the line item is a charge or credit for a plan or add-on, this is the plan’s code.

Type

str

plan_id

If the line item is a charge or credit for a plan or add-on, this is the plan’s ID.

Type

str

previous_line_item_id

Will only have a value if the line item is a credit created from a previous credit, or if the credit was created from a charge refund.

Type

str

product_code

For plan-related line items this will be the plan’s code, for add-on related line items it will be the add-on’s code. For item-related line items it will be the item’s external_sku.

Type

str

proration_rate

When a line item has been prorated, this is the rate of the proration. Proration rates were made available for line items created after March 30, 2017. For line items created prior to that date, the proration rate will be null, even if the line item was prorated.

Type

float

quantity

This number will be multiplied by the unit amount to compute the subtotal before any discounts or taxes.

Type

int

refund

Refund?

Type

bool

refunded_quantity

For refund charges, the quantity being refunded. For non-refund charges, the total quantity refunded (possibly over multiple refunds).

Type

int

revenue_schedule_type

Revenue schedule type

Type

str

shipping_address
Type

ShippingAddress

start_date

If an end date is present, this is value indicates the beginning of a billing time range. If no end date is present it indicates billing for a specific date.

Type

datetime

state

Pending line items are charges or credits on an account that have not been applied to an invoice yet. Invoiced line items will always have an invoice_id value.

Type

str

subscription_id

If the line item is a charge or credit for a subscription, this is its ID.

Type

str

subtotal

quantity * unit_amount

Type

float

tax

The tax amount for the line item.

Type

float

tax_code

Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use unknown, physical, or digital.

Type

str

tax_exempt

true exempts tax on charges, false applies tax on charges. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative line items). Credits are always applied post-tax. Pre-tax discounts should use the Coupons feature.

Type

bool

tax_info

Tax info

Type

TaxInfo

taxable

true if the line item is taxable, false if it is not.

Type

bool

type

Charges are positive line items that debit the account. Credits are negative line items that credit the account.

Type

str

unit_amount

Positive amount for a charge, negative amount for a credit.

Type

float

updated_at

When the line item was last changed.

Type

datetime

uuid

The UUID is useful for matching data with the CSV exports and building URLs into Recurly’s UI.

Type

str

schema = {'account': 'AccountMini', 'accounting_code': <class 'str'>, 'add_on_code': <class 'str'>, 'add_on_id': <class 'str'>, 'amount': <class 'float'>, 'avalara_service_type': <class 'int'>, 'avalara_transaction_type': <class 'int'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'credit_applied': <class 'float'>, 'credit_reason_code': <class 'str'>, 'currency': <class 'str'>, 'description': <class 'str'>, 'discount': <class 'float'>, 'end_date': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'external_sku': <class 'str'>, 'id': <class 'str'>, 'invoice_id': <class 'str'>, 'invoice_number': <class 'str'>, 'item_code': <class 'str'>, 'item_id': <class 'str'>, 'legacy_category': <class 'str'>, 'object': <class 'str'>, 'origin': <class 'str'>, 'original_line_item_invoice_id': <class 'str'>, 'plan_code': <class 'str'>, 'plan_id': <class 'str'>, 'previous_line_item_id': <class 'str'>, 'product_code': <class 'str'>, 'proration_rate': <class 'float'>, 'quantity': <class 'int'>, 'refund': <class 'bool'>, 'refunded_quantity': <class 'int'>, 'revenue_schedule_type': <class 'str'>, 'shipping_address': 'ShippingAddress', 'start_date': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'state': <class 'str'>, 'subscription_id': <class 'str'>, 'subtotal': <class 'float'>, 'tax': <class 'float'>, 'tax_code': <class 'str'>, 'tax_exempt': <class 'bool'>, 'tax_info': 'TaxInfo', 'taxable': <class 'bool'>, 'type': <class 'str'>, 'unit_amount': <class 'float'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'uuid': <class 'str'>}
class recurly.resources.LineItemList

Bases: recurly.resource.Resource

data
Type

list of LineItem

has_more

Indicates there are more results on subsequent pages.

Type

bool

next

Path to subsequent page of results.

Type

str

object

Will always be List.

Type

str

schema = {'data': ['LineItem'], 'has_more': <class 'bool'>, 'next': <class 'str'>, 'object': <class 'str'>}
class recurly.resources.MeasuredUnit

Bases: recurly.resource.Resource

created_at

Created at

Type

datetime

deleted_at

Deleted at

Type

datetime

description

Optional internal description.

Type

str

display_name

Display name for the measured unit. Can only contain spaces, underscores and must be alphanumeric.

Type

str

id

Item ID

Type

str

name

Unique internal name of the measured unit on your site.

Type

str

object

Object type

Type

str

state

The current state of the measured unit.

Type

str

updated_at

Last updated at

Type

datetime

schema = {'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'deleted_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'description': <class 'str'>, 'display_name': <class 'str'>, 'id': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>, 'state': <class 'str'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.PaymentMethod

Bases: recurly.resource.Resource

account_type

The bank account type. Only present for ACH payment methods.

Type

str

billing_agreement_id

Billing Agreement identifier. Only present for Amazon or Paypal payment methods.

Type

str

card_type

Visa, MasterCard, American Express, Discover, JCB, etc.

Type

str

exp_month

Expiration month.

Type

int

exp_year

Expiration year.

Type

int

first_six

Credit card number’s first six digits.

Type

str

gateway_code

An identifier for a specific payment gateway.

Type

str

gateway_token

A token used in place of a credit card in order to perform transactions.

Type

str

last_four

Credit card number’s last four digits. Will refer to bank account if payment method is ACH.

Type

str

last_two

The IBAN bank account’s last two digits.

Type

str

name_on_account

The name associated with the bank account.

Type

str

object
Type

str

routing_number

The bank account’s routing number. Only present for ACH payment methods.

Type

str

routing_number_bank

The bank name of this routing number.

Type

str

schema = {'account_type': <class 'str'>, 'billing_agreement_id': <class 'str'>, 'card_type': <class 'str'>, 'exp_month': <class 'int'>, 'exp_year': <class 'int'>, 'first_six': <class 'str'>, 'gateway_code': <class 'str'>, 'gateway_token': <class 'str'>, 'last_four': <class 'str'>, 'last_two': <class 'str'>, 'name_on_account': <class 'str'>, 'object': <class 'str'>, 'routing_number': <class 'str'>, 'routing_number_bank': <class 'str'>}
class recurly.resources.Plan

Bases: recurly.resource.Resource

accounting_code

Accounting code for invoice line items for the plan. If no value is provided, it defaults to plan’s code.

Type

str

allow_any_item_on_subscriptions

Used to determine whether items can be assigned as add-ons to individual subscriptions. If true, items can be assigned as add-ons to individual subscription add-ons. If false, only plan add-ons can be used.

Type

bool

auto_renew

Subscriptions will automatically inherit this value once they are active. If auto_renew is true, then a subscription will automatically renew its term at renewal. If auto_renew is false, then a subscription will expire at the end of its term. auto_renew can be overridden on the subscription record itself.

Type

bool

avalara_service_type

Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the plan is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types.

Type

int

avalara_transaction_type

Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the plan is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types.

Type

int

code

Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.

Type

str

created_at

Created at

Type

datetime

currencies

Pricing

Type

list of PlanPricing

deleted_at

Deleted at

Type

datetime

description

Optional description, not displayed.

Type

str

hosted_pages

Hosted pages settings

Type

PlanHostedPages

id

Plan ID

Type

str

interval_length

Length of the plan’s billing interval in interval_unit.

Type

int

interval_unit

Unit for the plan’s billing interval.

Type

str

name

This name describes your plan and will appear on the Hosted Payment Page and the subscriber’s invoice.

Type

str

object

Object type

Type

str

revenue_schedule_type

Revenue schedule type

Type

str

setup_fee_accounting_code

Accounting code for invoice line items for the plan’s setup fee. If no value is provided, it defaults to plan’s accounting code.

Type

str

setup_fee_revenue_schedule_type

Setup fee revenue schedule type

Type

str

state

The current state of the plan.

Type

str

tax_code

Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use unknown, physical, or digital.

Type

str

tax_exempt

true exempts tax on the plan, false applies tax on the plan.

Type

bool

total_billing_cycles

Automatically terminate subscriptions after a defined number of billing cycles. Number of billing cycles before the plan automatically stops renewing, defaults to null for continuous, automatic renewal.

Type

int

trial_length

Length of plan’s trial period in trial_units. 0 means no trial.

Type

int

trial_requires_billing_info

Allow free trial subscriptions to be created without billing info.

Type

bool

trial_unit

Units for the plan’s trial period.

Type

str

updated_at

Last updated at

Type

datetime

schema = {'accounting_code': <class 'str'>, 'allow_any_item_on_subscriptions': <class 'bool'>, 'auto_renew': <class 'bool'>, 'avalara_service_type': <class 'int'>, 'avalara_transaction_type': <class 'int'>, 'code': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'currencies': ['PlanPricing'], 'deleted_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'description': <class 'str'>, 'hosted_pages': 'PlanHostedPages', 'id': <class 'str'>, 'interval_length': <class 'int'>, 'interval_unit': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>, 'revenue_schedule_type': <class 'str'>, 'setup_fee_accounting_code': <class 'str'>, 'setup_fee_revenue_schedule_type': <class 'str'>, 'state': <class 'str'>, 'tax_code': <class 'str'>, 'tax_exempt': <class 'bool'>, 'total_billing_cycles': <class 'int'>, 'trial_length': <class 'int'>, 'trial_requires_billing_info': <class 'bool'>, 'trial_unit': <class 'str'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.PlanHostedPages

Bases: recurly.resource.Resource

bypass_confirmation

If true, the customer will be sent directly to your success_url after a successful signup, bypassing Recurly’s hosted confirmation page.

Type

bool

cancel_url

URL to redirect to on canceled signup on the hosted payment pages.

Type

str

display_quantity

Determines if the quantity field is displayed on the hosted pages for the plan.

Type

bool

success_url

URL to redirect to after signup on the hosted payment pages.

Type

str

schema = {'bypass_confirmation': <class 'bool'>, 'cancel_url': <class 'str'>, 'display_quantity': <class 'bool'>, 'success_url': <class 'str'>}
class recurly.resources.PlanMini

Bases: recurly.resource.Resource

code

Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.

Type

str

id

Plan ID

Type

str

name

This name describes your plan and will appear on the Hosted Payment Page and the subscriber’s invoice.

Type

str

object

Object type

Type

str

schema = {'code': <class 'str'>, 'id': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>}
class recurly.resources.PlanPricing

Bases: recurly.resource.Resource

currency

3-letter ISO 4217 currency code.

Type

str

setup_fee

Amount of one-time setup fee automatically charged at the beginning of a subscription billing cycle. For subscription plans with a trial, the setup fee will be charged at the time of signup. Setup fees do not increase with the quantity of a subscription plan.

Type

float

unit_amount

Unit price

Type

float

schema = {'currency': <class 'str'>, 'setup_fee': <class 'float'>, 'unit_amount': <class 'float'>}
class recurly.resources.Pricing

Bases: recurly.resource.Resource

currency

3-letter ISO 4217 currency code.

Type

str

unit_amount

Unit price

Type

float

schema = {'currency': <class 'str'>, 'unit_amount': <class 'float'>}
class recurly.resources.Settings

Bases: recurly.resource.Resource

accepted_currencies
Type

list of str

billing_address_requirement
  • full: Full Address (Street, City, State, Postal Code and Country)

  • streetzip: Street and Postal Code only

  • zip: Postal Code only

  • none: No Address

Type

str

default_currency

The default 3-letter ISO 4217 currency code.

Type

str

schema = {'accepted_currencies': <class 'list'>, 'billing_address_requirement': <class 'str'>, 'default_currency': <class 'str'>}
class recurly.resources.ShippingAddress

Bases: recurly.resource.Resource

account_id

Account ID

Type

str

city
Type

str

company
Type

str

country

Country, 2-letter ISO code.

Type

str

created_at

Created at

Type

datetime

email
Type

str

first_name
Type

str

id

Shipping Address ID

Type

str

last_name
Type

str

nickname
Type

str

object

Object type

Type

str

phone
Type

str

postal_code

Zip or postal code.

Type

str

region

State or province.

Type

str

street1
Type

str

street2
Type

str

updated_at

Updated at

Type

datetime

vat_number
Type

str

schema = {'account_id': <class 'str'>, 'city': <class 'str'>, 'company': <class 'str'>, 'country': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'email': <class 'str'>, 'first_name': <class 'str'>, 'id': <class 'str'>, 'last_name': <class 'str'>, 'nickname': <class 'str'>, 'object': <class 'str'>, 'phone': <class 'str'>, 'postal_code': <class 'str'>, 'region': <class 'str'>, 'street1': <class 'str'>, 'street2': <class 'str'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'vat_number': <class 'str'>}
class recurly.resources.ShippingMethod

Bases: recurly.resource.Resource

accounting_code

Accounting code for shipping method.

Type

str

code

The internal name used identify the shipping method.

Type

str

created_at

Created at

Type

datetime

deleted_at

Deleted at

Type

datetime

id

Shipping Method ID

Type

str

name

The name of the shipping method displayed to customers.

Type

str

object

Object type

Type

str

tax_code

Used by Avalara, Vertex, and Recurly’s built-in tax feature. The tax code values are specific to each tax system. If you are using Recurly’s built-in taxes the values are:

  • FR – Common Carrier FOB Destination

  • FR022000 – Common Carrier FOB Origin

  • FR020400 – Non Common Carrier FOB Destination

  • FR020500 – Non Common Carrier FOB Origin

  • FR010100 – Delivery by Company Vehicle Before Passage of Title

  • FR010200 – Delivery by Company Vehicle After Passage of Title

  • NT – Non-Taxable

Type

str

updated_at

Last updated at

Type

datetime

schema = {'accounting_code': <class 'str'>, 'code': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'deleted_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'id': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>, 'tax_code': <class 'str'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.ShippingMethodMini

Bases: recurly.resource.Resource

code

The internal name used identify the shipping method.

Type

str

id

Shipping Method ID

Type

str

name

The name of the shipping method displayed to customers.

Type

str

object

Object type

Type

str

schema = {'code': <class 'str'>, 'id': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>}
class recurly.resources.Site

Bases: recurly.resource.Resource

address
Type

Address

created_at

Created at

Type

datetime

deleted_at

Deleted at

Type

datetime

features

A list of features enabled for the site.

Type

list of str

id

Site ID

Type

str

mode

Mode

Type

str

object

Object type

Type

str

public_api_key

This value is used to configure RecurlyJS to submit tokenized billing information.

Type

str

settings
Type

Settings

subdomain
Type

str

updated_at

Updated at

Type

datetime

schema = {'address': 'Address', 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'deleted_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'features': <class 'list'>, 'id': <class 'str'>, 'mode': <class 'str'>, 'object': <class 'str'>, 'public_api_key': <class 'str'>, 'settings': 'Settings', 'subdomain': <class 'str'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.Subscription

Bases: recurly.resource.Resource

account

Account mini details

Type

AccountMini

activated_at

Activated at

Type

datetime

add_ons

Add-ons

Type

list of SubscriptionAddOn

add_ons_total

Total price of add-ons

Type

float

auto_renew

Whether the subscription renews at the end of its term.

Type

bool

bank_account_authorized_at

Recurring subscriptions paid with ACH will have this attribute set. This timestamp is used for alerting customers to reauthorize in 3 years in accordance with NACHA rules. If a subscription becomes inactive or the billing info is no longer a bank account, this timestamp is cleared.

Type

datetime

billing_info_id

Billing Info ID.

Type

str

canceled_at

Canceled at

Type

datetime

collection_method

Collection method

Type

str

coupon_redemptions

Coupon redemptions

Type

list of CouponRedemptionMini

created_at

Created at

Type

datetime

currency

3-letter ISO 4217 currency code.

Type

str

current_period_ends_at

Current billing period ends at

Type

datetime

current_period_started_at

Current billing period started at

Type

datetime

current_term_ends_at

When the term ends. This is calculated by a plan’s interval and total_billing_cycles in a term. Subscription changes with a timeframe=renewal will be applied on this date.

Type

datetime

current_term_started_at

The start date of the term when the first billing period starts. The subscription term is the length of time that a customer will be committed to a subscription. A term can span multiple billing periods.

Type

datetime

custom_fields

The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.

Type

list of CustomField

customer_notes

Customer notes

Type

str

expiration_reason

Expiration reason

Type

str

expires_at

Expires at

Type

datetime

id

Subscription ID

Type

str

net_terms

Integer representing the number of days after an invoice’s creation that the invoice will become past due. If an invoice’s net terms are set to ‘0’, it is due ‘On Receipt’ and will become past due 24 hours after it’s created. If an invoice is due net 30, it will become past due at 31 days exactly.

Type

int

object

Object type

Type

str

paused_at

Null unless subscription is paused or will pause at the end of the current billing period.

Type

datetime

pending_change

Subscription Change

Type

SubscriptionChange

plan

Just the important parts.

Type

PlanMini

po_number

For manual invoicing, this identifies the PO number associated with the subscription.

Type

str

quantity

Subscription quantity

Type

int

remaining_billing_cycles

The remaining billing cycles in the current term.

Type

int

remaining_pause_cycles

Null unless subscription is paused or will pause at the end of the current billing period.

Type

int

renewal_billing_cycles

If auto_renew=true, when a term completes, total_billing_cycles takes this value as the length of subsequent terms. Defaults to the plan’s total_billing_cycles.

Type

int

revenue_schedule_type

Revenue schedule type

Type

str

shipping

Subscription shipping details

Type

SubscriptionShipping

state

State

Type

str

subtotal

Estimated total, before tax.

Type

float

terms_and_conditions

Terms and conditions

Type

str

total_billing_cycles

The number of cycles/billing periods in a term. When remaining_billing_cycles=0, if auto_renew=true the subscription will renew and a new term will begin, otherwise the subscription will expire.

Type

int

trial_ends_at

Trial period ends at

Type

datetime

trial_started_at

Trial period started at

Type

datetime

unit_amount

Subscription unit price

Type

float

updated_at

Last updated at

Type

datetime

uuid

The UUID is useful for matching data with the CSV exports and building URLs into Recurly’s UI.

Type

str

schema = {'account': 'AccountMini', 'activated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'add_ons': ['SubscriptionAddOn'], 'add_ons_total': <class 'float'>, 'auto_renew': <class 'bool'>, 'bank_account_authorized_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'billing_info_id': <class 'str'>, 'canceled_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'collection_method': <class 'str'>, 'coupon_redemptions': ['CouponRedemptionMini'], 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'currency': <class 'str'>, 'current_period_ends_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'current_period_started_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'current_term_ends_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'current_term_started_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'custom_fields': ['CustomField'], 'customer_notes': <class 'str'>, 'expiration_reason': <class 'str'>, 'expires_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'id': <class 'str'>, 'net_terms': <class 'int'>, 'object': <class 'str'>, 'paused_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'pending_change': 'SubscriptionChange', 'plan': 'PlanMini', 'po_number': <class 'str'>, 'quantity': <class 'int'>, 'remaining_billing_cycles': <class 'int'>, 'remaining_pause_cycles': <class 'int'>, 'renewal_billing_cycles': <class 'int'>, 'revenue_schedule_type': <class 'str'>, 'shipping': 'SubscriptionShipping', 'state': <class 'str'>, 'subtotal': <class 'float'>, 'terms_and_conditions': <class 'str'>, 'total_billing_cycles': <class 'int'>, 'trial_ends_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'trial_started_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'unit_amount': <class 'float'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'uuid': <class 'str'>}
class recurly.resources.SubscriptionAddOn

Bases: recurly.resource.Resource

add_on

Just the important parts.

Type

AddOnMini

add_on_source

Used to determine where the associated add-on data is pulled from. If this value is set to plan_add_on or left blank, then add-on data will be pulled from the plan’s add-ons. If the associated plan has allow_any_item_on_subscriptions set to true and this field is set to item, then the associated add-on data will be pulled from the site’s item catalog.

Type

str

created_at

Created at

Type

datetime

expired_at

Expired at

Type

datetime

id

Subscription Add-on ID

Type

str

object

Object type

Type

str

quantity

Add-on quantity

Type

int

revenue_schedule_type

Revenue schedule type

Type

str

subscription_id

Subscription ID

Type

str

tier_type

The type of tiering used by the Add-on.

Type

str

tiers

If tiers are provided in the request, all existing tiers on the Subscription Add-on will be removed and replaced by the tiers in the request.

Type

list of SubscriptionAddOnTier

unit_amount

This is priced in the subscription’s currency.

Type

float

updated_at

Updated at

Type

datetime

usage_percentage

The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if add_on_type is usage and usage_type is percentage.

Type

float

schema = {'add_on': 'AddOnMini', 'add_on_source': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'expired_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'id': <class 'str'>, 'object': <class 'str'>, 'quantity': <class 'int'>, 'revenue_schedule_type': <class 'str'>, 'subscription_id': <class 'str'>, 'tier_type': <class 'str'>, 'tiers': ['SubscriptionAddOnTier'], 'unit_amount': <class 'float'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'usage_percentage': <class 'float'>}
class recurly.resources.SubscriptionAddOnTier

Bases: recurly.resource.Resource

ending_quantity

Ending quantity

Type

int

unit_amount

Unit amount

Type

float

schema = {'ending_quantity': <class 'int'>, 'unit_amount': <class 'float'>}
class recurly.resources.SubscriptionChange

Bases: recurly.resource.Resource

activate_at

Activated at

Type

datetime

activated

Returns true if the subscription change is activated.

Type

bool

add_ons

These add-ons will be used when the subscription renews.

Type

list of SubscriptionAddOn

created_at

Created at

Type

datetime

custom_fields

The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.

Type

list of CustomField

deleted_at

Deleted at

Type

datetime

id

The ID of the Subscription Change.

Type

str

invoice_collection

Invoice Collection

Type

InvoiceCollection

object

Object type

Type

str

plan

Just the important parts.

Type

PlanMini

quantity

Subscription quantity

Type

int

revenue_schedule_type

Revenue schedule type

Type

str

setup_fee_revenue_schedule_type

Setup fee revenue schedule type

Type

str

shipping

Subscription shipping details

Type

SubscriptionShipping

subscription_id

The ID of the subscription that is going to be changed.

Type

str

unit_amount

Unit amount

Type

float

updated_at

Updated at

Type

datetime

schema = {'activate_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'activated': <class 'bool'>, 'add_ons': ['SubscriptionAddOn'], 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'custom_fields': ['CustomField'], 'deleted_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'id': <class 'str'>, 'invoice_collection': 'InvoiceCollection', 'object': <class 'str'>, 'plan': 'PlanMini', 'quantity': <class 'int'>, 'revenue_schedule_type': <class 'str'>, 'setup_fee_revenue_schedule_type': <class 'str'>, 'shipping': 'SubscriptionShipping', 'subscription_id': <class 'str'>, 'unit_amount': <class 'float'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.SubscriptionChangePreview

Bases: recurly.resource.Resource

activate_at

Activated at

Type

datetime

activated

Returns true if the subscription change is activated.

Type

bool

add_ons

These add-ons will be used when the subscription renews.

Type

list of SubscriptionAddOn

created_at

Created at

Type

datetime

custom_fields

The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.

Type

list of CustomField

deleted_at

Deleted at

Type

datetime

id

The ID of the Subscription Change.

Type

str

invoice_collection

Invoice Collection

Type

InvoiceCollection

object

Object type

Type

str

plan

Just the important parts.

Type

PlanMini

quantity

Subscription quantity

Type

int

revenue_schedule_type

Revenue schedule type

Type

str

setup_fee_revenue_schedule_type

Setup fee revenue schedule type

Type

str

shipping

Subscription shipping details

Type

SubscriptionShipping

subscription_id

The ID of the subscription that is going to be changed.

Type

str

unit_amount

Unit amount

Type

float

updated_at

Updated at

Type

datetime

schema = {'activate_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'activated': <class 'bool'>, 'add_ons': ['SubscriptionAddOn'], 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'custom_fields': ['CustomField'], 'deleted_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'id': <class 'str'>, 'invoice_collection': 'InvoiceCollection', 'object': <class 'str'>, 'plan': 'PlanMini', 'quantity': <class 'int'>, 'revenue_schedule_type': <class 'str'>, 'setup_fee_revenue_schedule_type': <class 'str'>, 'shipping': 'SubscriptionShipping', 'subscription_id': <class 'str'>, 'unit_amount': <class 'float'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.SubscriptionShipping

Bases: recurly.resource.Resource

address
Type

ShippingAddress

amount

Subscription’s shipping cost

Type

float

method
Type

ShippingMethodMini

object

Object type

Type

str

schema = {'address': 'ShippingAddress', 'amount': <class 'float'>, 'method': 'ShippingMethodMini', 'object': <class 'str'>}
class recurly.resources.TaxInfo

Bases: recurly.resource.Resource

rate

Rate

Type

float

region

Provides the tax region applied on an invoice. For U.S. Sales Tax, this will be the 2 letter state code. For EU VAT this will be the 2 letter country code. For all country level tax types, this will display the regional tax, like VAT, GST, or PST.

Type

str

type

Provides the tax type as “vat” for EU VAT, “usst” for U.S. Sales Tax, or the 2 letter country code for country level tax types like Canada, Australia, New Zealand, Israel, and all non-EU European countries.

Type

str

schema = {'rate': <class 'float'>, 'region': <class 'str'>, 'type': <class 'str'>}
class recurly.resources.Tier

Bases: recurly.resource.Resource

currencies

Tier pricing

Type

list of Pricing

ending_quantity

Ending quantity

Type

int

schema = {'currencies': ['Pricing'], 'ending_quantity': <class 'int'>}
class recurly.resources.Transaction

Bases: recurly.resource.Resource

account

Account mini details

Type

AccountMini

amount

Total transaction amount sent to the payment gateway.

Type

float

avs_check

When processed, result from checking the overall AVS on the transaction.

Type

str

billing_address
Type

Address

collected_at

Collected at, or if not collected yet, the time the transaction was created.

Type

datetime

collection_method

The method by which the payment was collected.

Type

str

created_at

Created at

Type

datetime

currency

3-letter ISO 4217 currency code.

Type

str

customer_message

For declined (success=false) transactions, the message displayed to the customer.

Type

str

customer_message_locale

Language code for the message

Type

str

cvv_check

When processed, result from checking the CVV/CVC value on the transaction.

Type

str

gateway_approval_code

Transaction approval code from the payment gateway.

Type

str

gateway_message

Transaction message from the payment gateway.

Type

str

gateway_reference

Transaction reference number from the payment gateway.

Type

str

gateway_response_code

For declined transactions (success=false), this field lists the gateway error code.

Type

str

gateway_response_time

Time, in seconds, for gateway to process the transaction.

Type

float

gateway_response_values

The values in this field will vary from gateway to gateway.

Type

dict

id

Transaction ID

Type

str

invoice

Invoice mini details

Type

InvoiceMini

ip_address_country

IP address’s country

Type

str

ip_address_v4

IP address provided when the billing information was collected:

  • When the customer enters billing information into the Recurly.js or Hosted Payment Pages, Recurly records the IP address.

  • When the merchant enters billing information using the API, the merchant may provide an IP address.

  • When the merchant enters billing information using the UI, no IP address is recorded.

Type

str

object

Object type

Type

str

origin

Describes how the transaction was triggered.

Type

str

original_transaction_id

If this transaction is a refund (type=refund), this will be the ID of the original transaction on the invoice being refunded.

Type

str

payment_gateway
Type

TransactionPaymentGateway

payment_method
Type

PaymentMethod

refunded

Indicates if part or all of this transaction was refunded.

Type

bool

status

The current transaction status. Note that the status may change, e.g. a pending transaction may become declined or success may later become void.

Type

str

status_code

Status code

Type

str

status_message

For declined (success=false) transactions, the message displayed to the merchant.

Type

str

subscription_ids

If the transaction is charging or refunding for one or more subscriptions, these are their IDs.

Type

list of str

success

Did this transaction complete successfully?

Type

bool

type
  • authorization – verifies billing information and places a hold on money in the customer’s account.

  • capture – captures funds held by an authorization and completes a purchase.

  • purchase – combines the authorization and capture in one transaction.

  • refund – returns all or a portion of the money collected in a previous transaction to the customer.

  • verify – a $0 or $1 transaction used to verify billing information which is immediately voided.

Type

str

updated_at

Updated at

Type

datetime

uuid

The UUID is useful for matching data with the CSV exports and building URLs into Recurly’s UI.

Type

str

voided_at

Voided at

Type

datetime

voided_by_invoice

Invoice mini details

Type

InvoiceMini

schema = {'account': 'AccountMini', 'amount': <class 'float'>, 'avs_check': <class 'str'>, 'billing_address': 'Address', 'collected_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'collection_method': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'currency': <class 'str'>, 'customer_message': <class 'str'>, 'customer_message_locale': <class 'str'>, 'cvv_check': <class 'str'>, 'gateway_approval_code': <class 'str'>, 'gateway_message': <class 'str'>, 'gateway_reference': <class 'str'>, 'gateway_response_code': <class 'str'>, 'gateway_response_time': <class 'float'>, 'gateway_response_values': <class 'dict'>, 'id': <class 'str'>, 'invoice': 'InvoiceMini', 'ip_address_country': <class 'str'>, 'ip_address_v4': <class 'str'>, 'object': <class 'str'>, 'origin': <class 'str'>, 'original_transaction_id': <class 'str'>, 'payment_gateway': 'TransactionPaymentGateway', 'payment_method': 'PaymentMethod', 'refunded': <class 'bool'>, 'status': <class 'str'>, 'status_code': <class 'str'>, 'status_message': <class 'str'>, 'subscription_ids': <class 'list'>, 'success': <class 'bool'>, 'type': <class 'str'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'uuid': <class 'str'>, 'voided_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'voided_by_invoice': 'InvoiceMini'}
class recurly.resources.TransactionError

Bases: recurly.resource.Resource

category

Category

Type

str

code

Code

Type

str

merchant_advice

Merchant message

Type

str

message

Customer message

Type

str

object

Object type

Type

str

three_d_secure_action_token_id

Returned when 3-D Secure authentication is required for a transaction. Pass this value to Recurly.js so it can continue the challenge flow.

Type

str

transaction_id

Transaction ID

Type

str

schema = {'category': <class 'str'>, 'code': <class 'str'>, 'merchant_advice': <class 'str'>, 'message': <class 'str'>, 'object': <class 'str'>, 'three_d_secure_action_token_id': <class 'str'>, 'transaction_id': <class 'str'>}
class recurly.resources.TransactionPaymentGateway

Bases: recurly.resource.Resource

id
Type

str

name
Type

str

object

Object type

Type

str

type
Type

str

schema = {'id': <class 'str'>, 'name': <class 'str'>, 'object': <class 'str'>, 'type': <class 'str'>}
class recurly.resources.UniqueCouponCode

Bases: recurly.resource.Resource

bulk_coupon_code

The Coupon code of the parent Bulk Coupon

Type

str

bulk_coupon_id

The Coupon ID of the parent Bulk Coupon

Type

str

code

The code the customer enters to redeem the coupon.

Type

str

created_at

Created at

Type

datetime

expired_at

The date and time the coupon was expired early or reached its max_redemptions.

Type

datetime

id

Unique Coupon Code ID

Type

str

object

Object type

Type

str

redeemed_at

The date and time the unique coupon code was redeemed.

Type

datetime

state

Indicates if the unique coupon code is redeemable or why not.

Type

str

updated_at

Updated at

Type

datetime

schema = {'bulk_coupon_code': <class 'str'>, 'bulk_coupon_id': <class 'str'>, 'code': <class 'str'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'expired_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'id': <class 'str'>, 'object': <class 'str'>, 'redeemed_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'state': <class 'str'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>}
class recurly.resources.Usage

Bases: recurly.resource.Resource

amount

The amount of usage. Can be positive, negative, or 0. No decimals allowed, we will strip them. If the usage-based add-on is billed with a percentage, your usage will be a monetary amount you will want to format in cents. (e.g., $5.00 is “500”).

Type

float

billed_at

When the usage record was billed on an invoice.

Type

datetime

created_at

When the usage record was created in Recurly.

Type

datetime

id
Type

str

measured_unit_id

The ID of the measured unit associated with the add-on the usage record is for.

Type

str

merchant_tag

Custom field for recording the id in your own system associated with the usage, so you can provide auditable usage displays to your customers using a GET on this endpoint.

Type

str

object

Object type

Type

str

recording_timestamp

When the usage was recorded in your system.

Type

datetime

tier_type

The pricing model for the add-on. For more information, [click here](https://docs.recurly.com/docs/billing-models#section-quantity-based).

Type

str

tiers

The tiers and prices of the subscription based on the usage_timestamp. If tier_type = flat, tiers = null

Type

list of SubscriptionAddOnTier

unit_amount

Unit price

Type

float

updated_at

When the usage record was billed on an invoice.

Type

datetime

usage_percentage

The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0.

Type

float

usage_timestamp

When the usage actually happened. This will define the line item dates this usage is billed under and is important for revenue recognition.

Type

datetime

usage_type

Type of usage, returns usage type if add_on_type is usage.

Type

str

schema = {'amount': <class 'float'>, 'billed_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'id': <class 'str'>, 'measured_unit_id': <class 'str'>, 'merchant_tag': <class 'str'>, 'object': <class 'str'>, 'recording_timestamp': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'tier_type': <class 'str'>, 'tiers': ['SubscriptionAddOnTier'], 'unit_amount': <class 'float'>, 'updated_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'usage_percentage': <class 'float'>, 'usage_timestamp': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'usage_type': <class 'str'>}
class recurly.resources.User

Bases: recurly.resource.Resource

created_at
Type

datetime

deleted_at
Type

datetime

email
Type

str

first_name
Type

str

id
Type

str

last_name
Type

str

object

Object type

Type

str

time_zone
Type

str

schema = {'created_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'deleted_at': <module 'datetime' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/datetime.py'>, 'email': <class 'str'>, 'first_name': <class 'str'>, 'id': <class 'str'>, 'last_name': <class 'str'>, 'object': <class 'str'>, 'time_zone': <class 'str'>}

recurly.response module

class recurly.response.Response(response, request)

Bases: object

Class representing a response from Recurly

recurly.response.parse_datetime_header(dictionary, key)

Defensively parse datetime header

recurly.response.parse_int_header(dictionary, key)

Defensively parse an int header

Module contents