# Subscribers

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

A subscriber is a payer's saved card, which you can charge without them. The payer saves it in the payment window; after that, charging it is a request of yours.

## Requests

| Request | What it does |
|---|---|
| `POST /v1/new`, with `"subscriber"` | [Create subscriber](https://docs.gjold.com/v1/subscribers/create): a link where the payer saves their card, and pays a first charge if you ask for one. |
| `POST /v1/subscribers/{subid}/charge` | [Charge subscriber](https://docs.gjold.com/v1/subscribers/charge) without the payer. Answers with the new transaction. |
| `POST /v1/subscribers/{subid}/renew` | [Renew subscriber](https://docs.gjold.com/v1/subscribers/renew): a link where the payer saves a new card for the subscriber. |

v1 can't delete a subscriber. To stop charging one, stop sending charges: we never charge on our own.

## How they fit together

1. [Create](https://docs.gjold.com/v1/subscribers/create) a link, and send the payer to it. When they have saved their card, seq returns the new subscriber, with your `"ref"`. Store its `"id"`.
2. [Charge](https://docs.gjold.com/v1/subscribers/charge) the subscriber when a payment is due. The charge answers with the transaction it created, which seq also returns, as a [charge](https://docs.gjold.com/v1/transactions#charges), and which you capture or refund as any transaction.
3. When the card stops working, or the payer wants to use another, [renew](https://docs.gjold.com/v1/subscribers/renew) the subscriber: a link like the first, after which seq returns the subscriber with a `"renew"` act.

We keep no schedule: when to charge, and how much, is yours to decide. See [Charging subscribers](https://docs.gjold.com/notes/subscribers). The first payment, in the payment window, is customer-initiated, and every charge after it merchant-initiated, which the card schemes treat differently: see the knowledge base's [Stored credentials](https://docs.gjold.com/learn/stored-credentials).

## The subscriber object

Every field is always there, as in a transaction; a field without a value is an empty string or an empty array.

| Field | Type | Description |
|---|---|---|
| `type` | string | `"subscriber"`. |
| `id` | integer | The subscriber's ID, the `{subid}` of its requests. A shop's subscribers are numbered from 1. |
| `rev` | integer | The revision: 1 when the subscriber is created, and one higher with each change, such as a renewal. |
| `ref` | string | Your reference, from [Create subscriber](https://docs.gjold.com/v1/subscribers/create). |
| `method.type` | string | Always `"card"`, also when the payer saved Apple Pay: `"services"` then has `"applepay"`. |
| `method.id` | string | An opaque ID of the card or device, as a [transaction](https://docs.gjold.com/v1/transactions#the-transaction-object)'s. |
| `method.card.brand` | string | The card's brand, as a transaction's. |
| `method.card.last4` | string | The last four digits of the card number. |
| `method.card.exp` | integer | The last moment the card is valid, in Unix time: the end of its expiry month. Ask the payer to renew before then. |
| `services` | array of strings | What took part when the card was last saved: `"3dsecurev2"` and `"applepay"`, or on older subscribers `"3dsecure"` and `"dsbn"`; and the acquiring agreement, such as `"nets-2"`. |
| `info.ip` | string | The IP address of the browser that last saved the card. |
| `time.created` | integer | When the link that created the subscriber was created, in Unix time. |
| `time.authorized` | integer | When the card was first saved, in Unix time. |
| `billing` | object | The billing address, as a transaction's, from when the subscriber was created or last renewed. |
| `shipping` | object | The shipping address, likewise. |
| `acts` | array of objects | What happened to it since it was created, oldest first: `"act": "renew"` when the payer saved a new card, with its `"time"` and the `"services"` that took part in it. |

A subscriber that the payer saved, and renewed once:

```json
{
    "type": "subscriber",
    "id": 19,
    "rev": 2,
    "ref": "user301",
    "method": {
        "type": "card",
        "id": "I2hfG55UvlDvAwzW8aVec1049giH0Z1ZEPlGYMPiCac=",
        "card": {
            "brand": "mastercard",
            "last4": "2847",
            "exp": 1848700800
        }
    },
    "services": [
        "3dsecurev2",
        "nets-2"
    ],
    "info": {
        "ip": "2001:db8:400f:804::200e"
    },
    "time": {
        "created": 1715259306,
        "authorized": 1715259314
    },
    "billing": {
        "name": "Anne Jensen",
        "company": "",
        "vatin": "",
        "gln": "",
        "email": "anne@example.com",
        "phone": "80781943",
        "address": ["Hans Christiansvænge 99", "Postboks 401"],
        "city": "Neder Vindinge",
        "zip": "4760",
        "state": "",
        "country": "DK"
    },
    "shipping": {
        "name": "",
        "company": "",
        "email": "",
        "phone": "",
        "address": [],
        "city": "",
        "zip": "",
        "state": "",
        "country": ""
    },
    "acts": [
        {
            "act": "renew",
            "time": 1757573571,
            "services": [
                "3dsecurev2",
                "nets-2"
            ]
        }
    ]
}
```