API versionv2 next

API version

API v2 is not live yet: it launches in early 2027, and until then these pages are its spec. Switch to v1 (live)

Subscribers

Renew subscriber

Create a link to the payment window, where the payer saves a new card for a subscriber: when theirs has expired, a charge failed for good, or the subscriber was deleted. The subscriber keeps its "id" and "ref", so you charge it as before.

Request

POST https://api.gjold.com/v2/{shopid}:sub:{subid}/renew
  • {subid} is the subscriber's "id", from seq.

The key needs the payid permission.

Headers

HTTP header Description
Authorization

Required. Your API key, after Basic and base64-encoded. See Authentication.
Content-Type application/json. We don't check it.

Fields

An address you send replaces the subscriber's, and one you leave out stays as it is.

Field Type Description
items array

A first charge, for the payer to pay as they save their card: one or more items, whose totals add up to more than 0, in one currency. See First charge.

For a renewal after a failed charge, this is often what the payer owes.
items[].total amount, required

The price of the item, its whole quantity together. At least 0, and with no more decimals than the currency has. See Amounts.
items[].quantity integer

How many, a positive integer. The default is 1. It is for your records and the dashboard: the "total" is already for all of them.
items[].name string

The name of the product or service, for your records and the dashboard. The payment window does not show it.
items[].sku string

Your SKU for the product.
orderid string

Your ID for the order that the first charge pays, which seq returns with the charge, and the acquirer passes to the payer's bank as its reference, as for a payment link.
autocapture boolean

Capture the first charge as soon as it is authorized. By default, false, it is only authorized, and you capture it later. With true, a capture that fails voids the authorization, and nothing is saved.
billing object The payer's new billing address. See Addresses.
shipping object The new shipping address.
successurl string

Where the payment window sends the payer when they have paid, with a GET and nothing added to the URL. Without it, the window shows a confirmation of its own. We don't check it, so make it an absolute https URL that works, and put in it what the page needs, such as your order ID. It is no proof of payment: see Orders and payment links.
language string

The payment window's language: "da", "en", "no", or "sv". A code with a region, such as "en-GB", counts as its language. Without one, or with another, the window takes the language from the payer's browser, and else uses English.
lifetime string

How long the link can be paid: a whole number and a unit, d, h, m, or s, as in "90m" or "7d". The default is "1h", and it can be from "5m" to "30d". The payer must be done, 3-D Secure included, before it ends. The longer the lifetime, the longer the link's ID: see The link's ID.

First charge

With "items", the payer pays a first charge as they save their card, such as a subscription's first month: one payment, authorized together with saving the card, for the items' total. If it fails, nothing is saved, and the payer can try again in the window. Seq returns it as a charge of the subscriber, after the subscriber, with the "orderid" and items of this request. Like any payment, it is declined if the bank approves only part of it.

Without "items", the payer only saves their card, and is charged nothing. "orderid" and "autocapture" are for the first charge, and do nothing without it.

Example

curl https://api.gjold.com/v2/{shopid}:sub:19/renew \
    -u {apikey} \
    -d @renew.json
{
    "orderid": "M-7192-2026-12",
    "items": [
        {
            "name": "Membership, December",
            "total": "99 DKK"
        }
    ],
    "successurl": "https://shop.example/renewed?user=7192"
}

Response

We answer 200 OK with the link, as Create payment link does:

Field Type Description
url string

The link: the payment window's address, to send the payer to.
id string

The link's ID, the {payid} by which you can delete it. Store it with the order.

The subscriber is not renewed yet. It is when the payer has saved their new card: seq then returns the subscriber with its new "method", a "renew" in its "acts", and its "rev" one higher. Until then, the old card is charged as before, if it still works. A link that expires unused changes nothing.

The payment window offers the payment methods that can be saved: cards, and Apple Pay. MobilePay can't be saved, so it is not offered. To take the payer to Apple Pay, add a parameter to the link's URL:

Link parameter What it does
?go=applepay Opens the payment window with Apple Pay in focus.

If the payer's device can't use Apple Pay, the parameter does nothing. The window always asks the payer's bank for 3-D Secure when they save a card, as the card schemes require of a stored card's first payment; Apple Pay authenticates on the device.

Errors

Besides the errors that any request can give, which Errors lists:

Status and message Description
400 invalid json in {where}: {why} The body is not a JSON object, or a field is not as the table says. See Invalid JSON.
400 total must be more than 0 There are "items", but their totals add up to 0.
400 invalid item total currency An item's total is in a currency that is not in the ISO 4217 table.
400 invalid lifetime The "lifetime" can't be read, or is under "5m" or over "30d".
404 subscriber not found The shop has no subscriber with that {subid}.
500 {why} We could not create the link just now. Try again.

A declined card is not an error of this request: the payer sees the decline in the payment window, and can try again there until the link expires. The request takes no Idempotency-Key, so a retry after a broken connection can create a second link. That does no harm, as no one has the first link's URL, and it expires unpaid.

A deleted subscriber can be renewed: the payer's new card makes it chargeable again.

When to ask the payer to renew, before their card expires or after a charge fails, is in the note Charging subscribers.