# Create

## `$kit->subscriptions->create()`

Creates a new subscription for an existing customer.

## Signature

```php
public function create(array $input): array
```

## Parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `customerId` | `string` | Yes | The customer to subscribe. |
| `priceId` | `string` | Yes | The Stripe Price to subscribe them to. |
| `userId` | `string\|int` | No | Your own internal user ID, stamped on the returned record. |
| `quantity` | `int` | No, defaults to `1` | Number of units of the price. |
| `trialPeriodDays` | `int` | No | Length of a free trial before the first charge. |
| `collectionMethod` | `'charge_automatically'\|'send_invoice'` | No, defaults to `'charge_automatically'` | Whether Stripe charges the default payment method automatically, or emails an invoice for manual payment. |
| `daysUntilDue` | `int` | Only with `send_invoice` | Defaults to `7`. |
| `defaultPaymentMethodId` | `string` | No | Payment method used for this subscription's charges. |
| `promotionCode` | `string` | No | A Stripe promotion code ID (not a plain code string) applied at creation. |
| `metadata` | `array<string,string>` | No | Merged with `source: "stripekit"`. |
| `fieldValues` | `array<string,string>` | No | Written into metadata as `field_<key>` and surfaced back as `fieldValues` on every subsequent read. |

## Example request

```php
$subscription = $kit->subscriptions->create([
    'customerId' => 'cus_R1a2B3c4D5e6F7',
    'priceId' => 'price_1P9k2K2eZvKYlo2Cexample',
    'trialPeriodDays' => 14,
    'fieldValues' => ['seats' => '5'],
]);
```

## Example response

```php
[
    'id' => 'sub_1P9k2K2eZvKYlo2Cexample',
    'userId' => null,
    'customerId' => 'cus_R1a2B3c4D5e6F7',
    'priceId' => 'price_1P9k2K2eZvKYlo2Cexample',
    'status' => 'trialing',
    'currentPeriodStartUtc' => '2026-08-12T09:30:00.000Z',
    'currentPeriodEndUtc' => '2026-08-26T09:30:00.000Z',
    'currentPeriodStartLocal' => '2026-08-12T11:30:00',
    'currentPeriodEndLocal' => '2026-08-26T11:30:00',
    'cancelAtPeriodEnd' => false,
    'canceledAtUtc' => null,
    'trialEndUtc' => '2026-08-26T09:30:00.000Z',
    'collectionMethod' => 'charge_automatically',
    'metadata' => ['source' => 'stripekit', 'field_seats' => '5'],
    'fieldValues' => ['seats' => '5'],
    'createdAtUtc' => '2026-08-12T09:30:00.000Z',
]
```

`...Local` fields shown assume `timezone: 'Europe/Amsterdam'` was configured on init.

## Errors

| Exception | When |
| --- | --- |
| `StripeOperationError` | The customer or price ID does not exist, the customer has no default payment method and one is required, or Stripe otherwise rejects the request. |

## Notes

- If a `storage` adapter is configured, the record is persisted via `saveSubscription()` immediately.
- Note that `promotionCode` expects a Stripe promotion code **ID**, not the plain-text code a customer types in. To apply a code by its plain text, validate it first with [`$kit->coupons->validate()`](/packagist-packages/stripekit/modules/coupons/validate), which returns a `stripePromotionCodeId` you can use here or with [`applyPromotionCode()`](/packagist-packages/stripekit/modules/subscriptions/apply-promotion-code).