Create a job

POST 
/subscriptions/jobs

Create a job

Request

Query Parameters

filter string

application/json

Body

data JobCreaterequired
type SubscriptionJobType (string)required
Possible values: [subscription_job]
attributes JobCreateAttributesrequired
external_ref ExternalRef (string)
Possible values: <= 2048 characters
A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
job_type JobType (string)required
Possible values: [billing-run, tax-run, payment-run, import]
The type of job. One of the following:
• billing_run - a billing run job.
• payment_run - a payment run job.
• tax_run - a tax run job.
taxes InvoiceTaxItems[]
Possible values: >= 1
Array [
invoice_id UUID (string)required
The unique identifier.
tax_items TaxItem[]required
Array [
type stringrequired
Possible values: [tax_item]
This represents the type of resource object being returned. Always tax_item.
name string
Possible values: <= 1024 characters
The name that appears on your customer's invoice and usually describes the specific type of tax, for example, Sales, VAT or GST.
code string
Possible values: <= 1024 characters
The unique identifier assigned to goods and services for taxation purposes.
rate doublerequired
The tax rate is the percentage of the subscription amount that is required to be paid as tax.
jurisdiction string
Possible values: <= 1024 characters
The geographic area or political entity that has authority to levy and collect taxes.
]
]

Responses

201

Success. The job was created.

application/json

Schema

Schema

data Job

id UUID (string)

The unique identifier.

type SubscriptionJobType (string)required

Possible values: [subscription_job]

attributes JobCreateAttributesrequired

external_ref ExternalRef (string)

Possible values: <= 2048 characters

A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

job_type JobType (string)required

Possible values: [billing-run, tax-run, payment-run, import]

The type of job. One of the following:

• billing_run - a billing run job.
• payment_run - a payment run job.
• tax_run - a tax run job.

taxes InvoiceTaxItems[]

Possible values: >= 1

Array [

invoice_id UUID (string)required

The unique identifier.

tax_items TaxItem[]required

Array [

type stringrequired

Possible values: [tax_item]

This represents the type of resource object being returned. Always tax_item.

name string

Possible values: <= 1024 characters

The name that appears on your customer's invoice and usually describes the specific type of tax, for example, Sales, VAT or GST.

code string

Possible values: <= 1024 characters

The unique identifier assigned to goods and services for taxation purposes.

rate doublerequired

The tax rate is the percentage of the subscription amount that is required to be paid as tax.

jurisdiction string

Possible values: <= 1024 characters

The geographic area or political entity that has authority to levy and collect taxes.

]

]

status stringrequired

Possible values: [pending, started, success, failed]

The status of job.

updated_at stringrequired

The date and time a resource was updated.

created_at stringrequired

The date and time a resource was created.

relationships Relationships

Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.

anyOf

title

meta JobMetarequired

owner stringrequired

The owner of a resource, either store or organization.

timestamps Timestampsrequired

updated_at stringrequired

The date and time a resource was updated.

created_at stringrequired

The date and time a resource was created.

started_at string

The date and time a job is started.

finished_at string

The date and time a job finished.

report object

You can track your Subscriptions billing, tax, and payment operations using reports.

oneOf

BillingRunReport

invoices_ready_for_payment integerrequired

The total number of invoices created that are ready for payment.

invoices_tax_required integerrequired

The total number of invoices created that need taxes to be applied before payment can be made.

invoice_failures integerrequired

The total number of invoices that were scheduled but creation failed.

total_ready_for_payment Pricerequired

The total amount ready for payment invoiced in the billing run, segmented by currency.

property name* object

The base price.

amount int64required

The value as a whole number of the currency's smallest subdivision.

includes_tax boolean

Indicates whether the amount includes any taxes.

total_tax_required Pricerequired

The total amount (excluding tax) invoiced in the billing run but still requiring taxes, segmented by currency.

property name* object

The base price.

amount int64required

The value as a whole number of the currency's smallest subdivision.

includes_tax boolean

Indicates whether the amount includes any taxes.

TaxRunReport

invoices_updated integerrequired

The total number of invoices to which tax was successfully added.

invoice_failures integerrequired

The total number of invoices to which tax could not be added.

PaymentRunReport

total_payment_attempts integerrequired

The total number of invoices for which payment was attempted.

failed_payments integerrequired

The number of failed payment attempts.

total_collected Pricerequired

The total amount collected by the payment run, segmented by currency.

property name* object

The base price.

amount int64required

The value as a whole number of the currency's smallest subdivision.

includes_tax boolean

Indicates whether the amount includes any taxes.

Example (from schema)

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "subscription_job",
    "attributes": {
      "external_ref": "abc123",
      "job_type": "billing-run",
      "taxes": [
        {
          "invoice_id": "00000000-0000-0000-0000-000000000000",
          "tax_items": [
            {
              "type": "tax_item",
              "name": "GST",
              "code": "20.0 % S",
              "rate": 0.2,
              "jurisdiction": "USA"
            }
          ]
        }
      ],
      "status": "pending",
      "updated_at": "2017-01-10T11:41:19.244842Z",
      "created_at": "2017-01-10T11:41:19.244842Z"
    },
    "relationships": {
      "plans": {
        "links": {
          "related": "/offerings/:offering-id/plans",
          "self": "/offerings/:offering-id"
        },
        "data": {
          "type": "offering-plan",
          "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"
        }
      }
    },
    "meta": {
      "owner": "store",
      "timestamps": {
        "updated_at": "2017-01-10T11:41:19.244842Z",
        "created_at": "2017-01-10T11:41:19.244842Z",
        "started_at": "2017-01-10T11:41:19.244842Z",
        "finished_at": "2017-01-10T11:41:19.244842Z"
      }
    }
  }
}

400

Bad request. The request failed validation.

application/json

Schema

Schema

errors Error[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

missing-name

{
  "errors": [
    {
      "title": "Validation Error",
      "status": "400",
      "detail": "data.attributes.name: \"name\" is required"
    }
  ]
}

409

Write conflict. Unable to perform the operation at this time.

application/json

Schema

Schema

errors Error[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

Example

{
  "errors": [
    {
      "title": "Write Conflict",
      "status": "409"
    }
  ]
}

500

Internal server error. There was a system failure in the platform.

application/json

Schema

Schema

errors Error[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

internal-server-error

{
  "errors": [
    {
      "title": "Internal Server Error",
      "status": "500"
    }
  ]
}

Loading...