QorePay - Api Documentation

Send an invoice to one or several clients

POST

https://gate.qorepay.com/api/v1/billing/

Use this endpoint to send a one time invoice(-s). Provide all data of a BillingTemplate (see Schemas below) and, additionally, an array of one or more BillingTemplateClients in clients . Purchases will be created and invoices sent, one for every Client you have specified.

A BillingTemplate won't be created; if you need to be able to issue repeated, similar invoices, see POST /billing_templates/ and POST /billing_templates/{id}/send_invoice/ .

Note that unlike for other requests where you can send BillingTemplate data (like POST /billing_templates/ ), title andis_subscription are read-only for POST /billing/.

HEADER PARAMS

authorization

String

required
Set value to BEARER SECRET_KEY

content-type

String

required
Set value to JSON

REQUEST BODY

clients

Object

required
Contains details about the clients you're sending this invoice to.
CLIENT OBJECT
client_id

string

required
ID of the Client object to add to the BillingTemplate. Read-only after the BillingTemplateClient has been created. Note that the same Client can be added to a BillingTemplate several times.
description

string

Connects a Client object to a BillingTemplate having is_subscription = true to store information about a single subscriber. You will be able to pause an individual subscription client's cycle by PATCH-ing its' status field to the value of subscription_paused.
invoice_reference

string

When present overrides reference for invoices generated for this client
status

enum
[pending, inactive, active, subscription_paused]
default = inactive

For subscriptions, you can edit (PATCH/billing_templates/{id}/clients/{id}/) this status between active and subscription_paused values to pause the client's subscription. Paused subscriptions run as normal, except for purchases not being created and invoices sent for them. It means that if you pause a BillingTemplateClient's monthly subscription cycle a day before the billing date, the next day the invoice will not be issued; but, if you unpause the client a day after the planned billing would have taken place, the planned billing in a month (minus one day) will happen as usual.
payment_method_whitelist

string

An optional whitelist of payment methods availble for purchases generated for this BillingTemplateClient. Copied 1:1 to Purchase.payment_method_whitelist field on created Purchases (see its description).
Payment method name as returned by GET/payment_methods/.
send_invoice_on_charge_failure

boolean

default: true
Sends invoice when subscription charge fails if this istrue
send_invoice_on_add_subscriber

boolean

default: false
Sends invoice when POST /billing_templates/{id}/add_subscriber/ is called if this is true
send_receipt

boolean

default: true
Sends receipt when subscription charge succeeds if this is true
purchase

Object

required
Core information about the Purchase, including the products, total, currency and invoice fields. If you're using invoicing via /billing/ or /billing_templates/, this object will be copied 1:1 from BillingTemplate you specify to the resulting Purchases (also to subscription Purchases).
currency

string

Currency code in the ISO 4217 standard (e.g. 'NGN').
products

array of objects

required
Line items of the invoice. In case of a transaction with no invoice sent, specify a single Product forming the cost of transaction.
PRODUCT OBJECT []
name

string

required
Currency code in the ISO 4217 standard (e.g. 'NGN').
price

integer

required
Amount of money as the smallest indivisible units of the currency. Example: 1 kobo for NGN. (100 = 1NGN)
quantity

string

Quantity of these products in invoice, where default value is 1 and minimum is 0.
discount

integer

Amount of money as the smallest indivisible units of the currency. Example: 1 kobo for NGN. (100 = 1NGN)

is_subscription

boolean

required
Defines whether this BillingTemplate issues invoices in a recurring manner - it's a subscription - or it sends invoices only once. You can't change this parameter when you edit the BillingTemplate. If this field is true , you will need to specify subscription_* fields and invoice_* fields are read-only, and vice-versa.
brand_id

string

string ID of the brand to create this BillingTemplate for. You can copy it down in the API section.
title

string
number_of_billing_cycles

integer

Limits number of billing cycles for each client if set to a non-zero value
invoice_issued

string($ISO 8601 (YYYY-MM-DD))

Sets issued on the Purchase objects generated. Generated from current day in purchase.timezone if not provided. Read-only if is_subscription == true.
invoice_due

integer($Unix timestamp (seconds)))

e.g :1619740800
Sets due on the Purchase objects generated. Required ifis_subscription == false, read-only otherwise.
invoice_send_receipt

boolean

default: false
Sets send_receipt on the Purchase objects generated. true by default (unlike in Purchases API, where by default receipts are not sent). Read-only if is_subscription == true.
subscription_period

integer

min: 1 max: 256
Defines how often are the subscription Purchases generated. Used together with subscription_period_units: to issue Purchases once a month, use "...period" : 1 and"...period_units" == "months".
Variable number of days in a month is respected; e.g. if subscription has a period of 1 month, a client had its billing cycle activated on January 30 and there are 28 days in February that year - billing scheduled for February will happen on 28th.
Both fields are required when creating a BillingTemplate with is_subscription == true/editing a BillingTemplate withis_subscription == true as long as there aren't any launched subscribers; they are read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.
subscription_period_units

string

[ days, weeks, months ]
default: months
See subscription_period.
subscription_due_period

integer

min: 1 max: 256
default: 7
Used to generate due on the Purchase objects generated. Used together with subscription_due_period_units: to set the final Purchase.due to a week after it's generated/invoice is sent, use "...period" : 1 and"...period_units" == "weeks". Required if is_subscription == true, read-only otherwise.
subscription_due_period_units

string

[ days, weeks, months ]
default: days
See subscription_due_period.
subscription_charge_period_end

boolean

default: false
If this is true, clients are charged at the end of billing periods, and vice-versa. E.g. if you add a subscriber client to a BillingTemplate, with this value being set to false , he will receive first invoice today, otherwise - after a single billing period (defined bysubscription_period / subscription_period_units) passes.
Required when creating a BillingTemplate withis_subscription == true/editing a BillingTemplate withis_subscription == true as long as there aren't any launched subscribers; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.
subscription_trial_periods

integer

minimum: 0maximum: 256
How many trial periods to give the client prior to starting his billing cycle. If billing period is 1 month and you set this value to 2, subscription will automatically adjust to giving your client 2 months without payments and then charging him for the 3rd month (when exactly depends onsubscription_charge_period_end: 3 months after the subscriber was launched for false, 4 for true)."subscription_trial_periods": 0 disables this feature.
Required when creating a BillingTemplate withis_subscription == true/editing a BillingTemplate withis_subscription == true as long as there aren't any launched subscribers; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if is_subscription == false.
subscription_active

boolean

default: false
Whether this subscription is paused. Has the same effect as setting "status": "subscription_paused" for every BillingTemplateClient launched for this subscription, see the description of status on BillingTemplateClient for more details.
ignore (read-only) if is_subscription == false.
force_recurring

boolean

default: false
If the used payment method supports recurring payment functionality, forces the customer's payment credentials to be saved for possible later recurring payments, without giving the customer a choice in the matter.

RESPONSES

200

OK

400

Invalid data submitted or request processing error

Query

Body


{
  "clients": [
    {
      "client_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "invoice_reference": "string",
      "status": "inactive",
      "payment_method_whitelist": [
        "string"
      ],
      "send_invoice_on_charge_failure": true,
      "send_invoice_on_add_subscriber": false,
      "send_receipt": true
    }
  ],
  "purchase": {
    "currency": "str",
    "products": [
      {
        "name": "string",
        "quantity": "1",
        "price": 0,
        "discount": 0,
        "tax_percent": "0",
        "category": "string"
      }
    ],
    "language": "en",
    "notes": "string",
    "debt": 0,
    "subtotal_override": null,
    "total_tax_override": null,
    "total_discount_override": null,
    "total_override": null,
    "request_client_details": [],
    "timezone": "Europe/Oslo",
    "due_strict": false
  },
  "number_of_billing_cycles": 0,
  "brand_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "string",
  "is_subscription": true,
  "invoice_issued": "2020-04-30",
  "invoice_due": 1619740800,
  "invoice_skip_capture": false,
  "invoice_send_receipt": false,
  "subscription_period": 1,
  "subscription_period_units": "months",
  "subscription_due_period": 7,
  "subscription_due_period_units": "days",
  "subscription_charge_period_end": false,
  "subscription_trial_periods": 0,
  "subscription_active": false,
  "force_recurring": false,
 
}

Sample Response

JSON


[
  "720e2c96-ef94-4baa-90b6-d61ef6fd675a"
]