Skip to main content

Jobs

Jobs are an asynchronous process that can be triggered manually or scheduled.

There are three types of job:

  • a billing run. Subscriptions generates an invoice when a billing run occurs. Billing runs generate invoices for the remaining billing cycles for each subscription. The invoice dates come from your plans. Billing runs are independent of payment runs.
  • a tax run. Invoices where tax_required is true will not have payment taken until a tax run has added the required tax to the invoice.
  • a payment run. The payment run identifies invoices that are 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.

By scheduling billing and payment runs, you automate the process, reducing manual intervention and ensuring the jobs are run in a timely manner. See Schedules.

Characteristics of Billing, Tax & Payments Jobs​

Billing and payment jobs have the following characteristics.

  • Jobs are asynchronous.
  • Jobs have a different status, depending on where a job is in its lifecycle.
  • Jobs report any errors to help you understand the reason for any failed jobs.
  • Only one billing run and payment run is allowed per store at a time. Although billing and payments are constantly generated, the jobs are queued. Subscriptions looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed.

Billing, Tax & Payments Jobs Lifecycle​

A job can have the following status types:

  • PENDING - Subscriptions has received the request but is currently busy processing other requests.
  • STARTED - Subscriptions has started processing the job.
  • SUCCESS - The job has successfully completed.
  • FAILED - The job has failed.

Billing, Tax & Payment Reports​

You can track your Subscriptions billing, payment and tax operations using reports. There are three types of report:

  • BillingRunReport - This report provides invoice summaries such as invoices ready for payment, invoices that require tax, and invoice failures.
  • TaxRunReport - This report provides invoice summaries such as invoices to which tax was successfully or unsuccessfully added.
  • PaymentRunReport - This report provides invoice summaries such as invoices for which payment was attempted, failed payment attempts and totals collected by a payment run.

See Get a job and List jobs.