# Create subscriber

Source: <https://docs.gjold.com/v1/subscribers/create>

Create a link to the payment window, where the payer saves their card, so that you can [charge](https://docs.gjold.com/v1/subscribers/charge) it later. Only the payer can save it, so this is the only way to create a subscriber. It is the request that [creates a payment link](https://docs.gjold.com/v1/payment-links/create), with a `"subscriber"`.

## Request

**POST** `https://api.gjold.com/v1/new`

The URL names no shop: the request is for the shop whose [API key](https://docs.gjold.com/v1/authentication) it has. The key needs the `payid` [permission](https://docs.gjold.com/v1/authentication#permissions).

### Headers

- `Authorization`

  **Required.** Your API key, after `Basic` and base64-encoded. See [Authentication](https://docs.gjold.com/v1/authentication).
- `Content-Type`

  `application/json`. We don't check it.

### Fields

- `subscriber` (object, **required**)

  Makes the link one where the payer saves their card. It may be empty, `{}`.
- `subscriber.ref` (string)

  Your reference for the subscriber, such as your customer ID, which seq returns with the subscriber and with each of its charges. We don't check that it is unique, and store it as it is: to change a subscriber's card, [renew](https://docs.gjold.com/v1/subscribers/renew) it rather than create another.
- `items` (array)

  A first charge, for the payer to pay as they save their card: one or more items, in one currency. See [First charge](https://docs.gjold.com/v1/subscribers/create#first-charge).
- `items[].total` (amount, **required**)

  The price of the item, its whole quantity together, as a string with its currency, as `"199.90 DKK"`. At least 0. Decimals beyond the currency's minor unit are cut off: `"10.999 DKK"` is 10.99 DKK. See [Amounts](https://docs.gjold.com/v1/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](https://en.wikipedia.org/wiki/Stock_keeping_unit) for the product. We accept it, but don't store it, so seq does not return it.
- `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](https://docs.gjold.com/v1/payment-links/create#fields).
- `autocapture` (boolean)

  Capture the first charge as soon as it is authorized. By default, `false`, it is only authorized, and you [capture](https://docs.gjold.com/v1/transactions/capture) it later. With `true`, a capture that fails voids the authorization, and nothing is saved; so does a bank that approves only part of the charge.
- `billing` (object)

  The payer's billing address, which seq returns with the subscriber, and with each charge that gives none of its own. See [Addresses](https://docs.gjold.com/v1/payment-links/create#addresses).
- `shipping` (object)

  The shipping address, likewise.
- `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](https://docs.gjold.com/notes/orders#the-success-page-is-no-proof).
- `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"`, or several, as in `"1d 12h"`. The default is `"1h"`, and it can be from 15 minutes to 30 days: a shorter lifetime is made 15 minutes, and a longer one 30 days. One we can't read is not an error, but gives the link the default or the shortest lifetime, so check yours. 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](https://docs.gjold.com/v1/payment-links/create#the-links-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](https://docs.gjold.com/v1/transactions#charges) of the subscriber, after the subscriber, with the `"orderid"` and items of this request. If the bank approves only part of it, the charge is for that part, unless it has `"autocapture"`, which declines it: check `totals.authorized`.

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

A link where the payer saves their card, and pays the first month:

```sh
curl https://api.gjold.com/v1/new \
    -u {apikey} \
    -d @create.json
```

```json
{
    "subscriber": {
        "ref": "user7192"
    },
    "orderid": "M-7192-2026-11",
    "items": [
        {
            "name": "Membership, first month",
            "total": "99 DKK"
        }
    ],
    "billing": {
        "name": "Anne Jensen",
        "email": "anne@example.com"
    },
    "successurl": "https://shop.example/welcome?user=7192"
}
```

## Response

We answer `200 OK` with the link, as [Create payment link](https://docs.gjold.com/v1/payment-links/create#response) does:

- `url` (string)

  The link: the payment window's address, to send the payer to. Its last part is the link's ID: see [The link's ID](https://docs.gjold.com/v1/payment-links/create#the-links-id).

No subscriber exists yet. We create it when the payer has saved their card, and [seq](https://docs.gjold.com/v1/synchronization/seq) returns it then, with your `"ref"` and the `"id"` by which you charge it. If the link expires unused, there is no subscriber, and seq returns nothing.

### Link parameters

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, and a subscriber's link takes no link parameters. The window always asks the payer's bank for [3-D Secure](https://docs.gjold.com/learn/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](https://docs.gjold.com/v1/errors) lists:

| Status and message | Description |
|---|---|
| `400 invalid json in {where}: {why}` | The body is not JSON, or an item's total can't be read, has no currency, or is in another currency than the items before it. See [Invalid JSON](https://docs.gjold.com/v1/errors#invalid-json). |
| `500 invalid item total currency` | An item's total is in a currency that is not in the [ISO 4217 table](https://docs.gjold.com/v1/amounts#currencies). Fix the request. |
| `500 {why}` | Any other failure: we could not create the link just now. Try again. |

Without `"subscriber"`, the request makes a payment link, which fails with `500 missing items` if there are no `"items"`: see [Create payment link](https://docs.gjold.com/v1/payment-links/create#errors).

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.

## See also

[Subscribers](https://docs.gjold.com/v1/subscribers), [Charge subscriber](https://docs.gjold.com/v1/subscribers/charge), [Renew subscriber](https://docs.gjold.com/v1/subscribers/renew), [Charging subscribers](https://docs.gjold.com/notes/subscribers), and in the knowledge base, [Stored credentials](https://docs.gjold.com/learn/stored-credentials).