Elastic Path Invoices API

Invoices represent the amount a customer owes for a subscription. Elastic Path Subscriptions generates an invoice for every period in a subscription billing cycle. Invoices provide:- an itemized list of goods and services provided by a subscription.- the cost of a subscription.- if applicable, any taxes.The invoice lifecycle is described below.1. When a subscription is created, an invoice for the first billing period is created. When a subscription is created as part of an order, the payment for the order covers the first billing period.2. Subscription invoices are created by [**billing runs**](/docs/api/subscriptions/jobs). The billing run identifies subscriptions that require a new invoice for their next billing period and creates them. At this point, invoices are marked as outstanding.3. Invoices where `tax_required` is `true` will not have payment taken until a tax run has added the required tax to the invoice. 3. The [**payment run**](/docs/api/subscriptions/jobs) identifies invoices that are still outstanding and attempts to take payment for them. If the payment succeeds the the invoice is no longer outstanding. If the payment fails for any reason, then the invoice remains outstanding and is picked up by the next payment run to retry the payment. If an invoice has a failed payment, payment is only retried if the fixed interval has passed from the last payment attempt as defined in Settings.### Payment RetriesIt is important to limit the number of times Subscriptions retries a failed payment request for many reasons, including: frequent payment retries can indicate fraudulent activities; multiple failed payment attempts can lead to customers accounts being locked out or flagged for suspicious activity resulting in poor customer experience; and excessive retries places an unnecessary load on your payment processing system.In Subscriptions, by default, the number of payment retries is 10. You can set this to a limit between 0 - 20, depending on your requirements. Each payment retry is made as a payment run. Once the number of payment retries reaches the limit, the payment retries stop, resulting in status of the invoice being unpaid. See [Invoices](#invoices).When configuring payment retries, you have the following options.| Attribute | Required | Description || --- | --- | --- || `payment_retry_type` | Optional | One of the following options: `fixed` - use `fixed` if you want a fixed time interval between payment retries.`backoff` - use `backoff` if you want the time between retry attempts to increase exponentially.`tiered` - use `tiered` if you want to specify a list of time durations. || `payment_retry_interval` | Optional | Represents the retry interval. For example, if `payment_retry_unit` is `week` and `payment_retry_interval` is `1` then, the payment retry interval is 1 week. || `payment_retry_multiplier` | Optional | Use when `payment_retry_type` is `tiered` and represents the factor by which the time duration increases after each retry. || `payment_retry_unit` | Optional | Represents the unit of time, either `day` or `week`. |### RoundingSubscriptions always rounds down to the penny. ### TaxSubscriptions allows you to apply any number of tax rates to your invoices and subscriptions. When applying a tax rate, you must specify:- a name that appears on your customer's invoice that describes the specific type of tax.- the tax rate which is the percentage of the subscription amount that is required to be paid as tax.In addition, you can optionally specify the jurisdiction which is the geographic area or political entity that has authority to levey and collect taxes.You can apply more than one tax rate for all items in an invoice. You cannot apply a tax rate per line item.### PaymentsWhen your customers add a subscription to a cart and the cart is checked out, an unpaid order is returned. You can process the payment for the order though a payment gateway. You can do this using:- Elastic Path Payments Powered by Stripe. The Elastic Path Payments Powered by Stripe gateway interacts with Stripe to allow your subscribers to pay for their subscriptions. - Authorize.Net. #### Using Elastic Path Payments Powered by StripeTo use Elastic Path Payments Powered by Stripe gateway, contact the [**Customer Success Team**](mailto:customersuccess@elasticpath.com). Create your Stripe account in [**Stripe Dashboard**](https://dashboard.stripe.com/login) and complete an onboarding form to make payments using the gateway. For more information, see [**Onboarding**](/docs/payments/onboarding).Once you have signed up for Elastic Path Payments Powered by Stripe, you must configure the payment gateway so that your shoppers can make payments. See [**Configure Elastic Path Payments Powered by Stripe**](/docs/payments/onboarding).#### Using Authorize.NetTo use Authorize.Net, you must have: - an active merchant account with Authorize.Net- obtained API credentials. These include an **API Login ID** and a **Transaction Key**.- Enabled Authorize.Net in Commerce Manager. See [Enabling Authorize.net](/docs/commerce-manager/payments/configure-other-payment-gateways#enabling-authorizenet).#### Payment RequestsSubscriptions only supports the `purchase` payment mechanism. The gateway attempts to charge the customer immediately, and the result of the attempt is returned. If a payment fails, the invoice is kept as outstanding and the payment information, with the reason for the failure is attached to the invoice. A new payment run is required to attempt another payment. When sending a payment request to the Payments service, you must specify the following.| Attribute | Required | Description || --- | --- | --- || `gateway` | Required| One of `elastic_path_payments_stripe`, `authorize_net` and `stripe_payment_intents`. || `method` | Required | Must be `purchase`.| `payment` | Required | The type of payment, for example, `pm_card_visa_debit`.| `options` | Required | These options must be set as they set up the card to be used in future without the customer being present. If these options are not set, future payments may fail. There are two options. `off_session`. Must be set to `true`. `confirm`. Must be set to `true`. |#### External PaymentsExternal payments are payment methods not offered by Elastic Path Subscriptions (such as Elastic Path Payments powered by Stripe or Authorize.net), but they can still be integrated with Subscriptions. To do this, you must configure your subscriptions to use external payments by setting `manual_payments` to `true`. See [Create a Subscription](/docs/api/subscriptions/create-subscription).When a subscription is created with `manual_payments` set to `true`:1. When the payment run processes the generated invoice, it creates a pending payment. A `subscription-invoice-created` event is emitted that includes the `subscription_id`, `invoice_id` and `payment_id`. No payment is taken. 2. You can use the events generated by Elastic Path Subscriptions to configure your external payment system to respond to these events, ensuring that your external payment system knows when the payment schedule has run and it's time to process the payment.3. When the external payment system handles the payment (either takes the payment successfully or the payment fails) the [Update Invoice Payment](/docs/api/subscriptions/update-invoice-payment) endpoint, enables the update of the pending payment. - If payment is successful, the invoice is updated to `paid` and the billing/payment cycle continues as normal. - If payment fails, the invoice continues to be marked as `outstanding`. The payment is not `pending` anymore. This is because a payment attempt has been made. Following on from this, the next payment run generates another manual pending payment. The external system is notified of this using the `subscription-invoice-payment-updated`.#### Card DeclinesCard payments can fail for a variety of reasons, including insufficient funds, incorrect card data or fraudulent activity. You can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details, enabling you to easily manage your subscription changes.