# Create Subscription

Use this API to create a new subscription. After a successful request, the response will include a payment link that you must redirect your customer to in order to complete the subscription setup. 

### Endpoint

``` 
POST https://demo-api.frontpayment.no/api/v1/connect/subscriptions/submit
```

### Authentication

This endpoint requires a `Bearer Token` for authentication. You will need to obtain this token from Front Payment and include it in the `Authorization` header of your request.

**Example Authorization Header:**
`Authorization: Bearer YOUR_FRONTPAID_BEARER_TOKEN`

### Request Payload

The request body should be a JSON object including the following elements:

```json
{
  "products": [
    {
      "name": "string",
      "productId": "string or null",
      "quantity": number,
      "rate": number,
      "discount": number (optional),
      "tax": number,
      "amount": number
    }
  ],
  "billingFrequency": "string",
  "numberOfRepeats": number,
  "orderSummary": {
    "subTotal": number,
    "totalTax": number,
    "totalDiscount": number,
    "grandTotal": number,
    "payablePerCycle": number
  },
  "subscriptionStartDate": "string",
  "subscriptionEndsDate": "string",
  "dueDateForPaymentLink": "string",
  "sendOrderBy": {
    "sms": boolean,
    "email": boolean
  },
  "customerDetails": {
    "type": "string or null",
    "countryCode": "string or null",
    "msisdn": "string or null",
    "email": "string or null (must be email format)",
    "name": "string",
    "personalNumber": "string or null",
    "organizationId": "string or null (when type=corporate)",
    // (other fields like preferredLanguage or address may apply in checkout session—refer to specific endpoints)
  }
}
```

### Validation Rules

The following table outlines validation constraints for each field in the request payload:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>products.*.name</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Name of the product.</td>
    </tr>
    <tr>
      <td><code>products.*.productId</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Unique identifier for the product.</td>
    </tr>
    <tr>
      <td><code>products.*.quantity</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Quantity of the product.</td>
    </tr>
    <tr>
      <td><code>products.*.rate</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Rate per unit of the product.</td>
    </tr>
    <tr>
      <td><code>products.*.discount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong>. Discount applied to the product.</td>
    </tr>
    <tr>
      <td><code>products.*.tax</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Tax rate (e.g., 0, 12, 15, 25). Unless you have other configuration.</td>
    </tr>
    <tr>
      <td><code>products.*.amount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Total amount for the product line item.</td>
    </tr>
    <tr>
      <td><code>billingFrequency</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Defines how often the billing occurs (e.g., daily, weekly, monthly)</td>
    </tr>
    <tr>
      <td><code>numberOfRepeats</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>Specifies how many times the billing cycle should be repeated.</td>
    </tr>
    <tr>
      <td><code>orderSummary.subTotal</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Subtotal of all products before tax and discount.</td>
    </tr>
    <tr>
      <td><code>orderSummary.totalTax</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Total tax for the order.</td>
    </tr>
    <tr>
      <td><code>orderSummary.totalDiscount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Total discount for the order.</td>
    </tr>
    <tr>
      <td><code>orderSummary.grandTotal</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Grand total of the order.</td>
    </tr>
    <tr>
      <td><code>orderSummary.payablePerCycle</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>Amount to be paid by the customer for each billing cycle.</td>
    </tr>
    <tr>
      <td><code>subscriptionStartDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> The date when the subscription becomes active.</td>
    </tr>
    <tr>
      <td><code>subscriptionEndsDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> The end date of subscription</td>
    </tr>
    <tr>
      <td><code>dueDateForPaymentLink</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Unix timestamp for the due date of the payment link.</td>
    </tr>
    <tr>
      <td><code>sendOrderBy.sms</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> If the payment link should send via sms</td>
    </tr>
    <tr>
      <td><code>sendOrderBy.email</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> If the payment link should send via email</td>
    </tr>
    <tr>
      <td><code>customerDetails.type</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Customer type must be either <code>private</code> or <code>corporate</code>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.countryCode</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Country code for the customer's phone number (e.g., "+47")</td>
    </tr>
    <tr>
      <td><code>customerDetails.msisdn</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Mobile Subscriber ISDN Number (phone number).</td>
    </tr>
    <tr>
      <td><code>customerDetails.email</code></td>
      <td><code>email</code></td>
      <td><strong>Required</strong>. Customer's email address.</td>
    </tr>
    <tr>
      <td><code>customerDetails.name</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Customer's full name.</td>
    </tr>
    <tr>
      <td><code>customerDetails.personalNumber</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Customer's personal identification number, must be 11 characters</td>
    </tr>
    <tr>
      <td><code>customerDetails.organizationId</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> if <code>customerDetails.type</code> is <code>corporate</code>. Must be number</td>
    </tr>
  </tbody>
</table>

### Responses

#### Successful Response

On success, you’ll receive a JSON response containing the status and a payment link to redirect the user:

```json
{
  "status_code": 200,
  "status_message": "OK",
  "message": "subscriptionCreatedSuccessfully",
  "is_data": true,
  "data": {
    "paymentLink": "https://…",
    "subscriptionUuid": "…",
    "orderUuid": "…",
    // Possibly other metadata
  }
}
```

You must redirect the customer to `paymentLink` to finalize the subscription. ([docs.frontpayment.no][1])

#### Error Responses

* **401 Unauthorized**: Missing or invalid Bearer token.
* Other validation errors will return appropriate HTTP error codes (e.g., `400 Bad Request`) along with error messages specifying the invalid or missing fields.