--- title: "Create Subscriptions" method: POST path: "/direct/subscription" --- # Create Subscriptions `POST /direct/subscription` ## Request - Base URL: `https://api.ksamerchant.geidea.net/subscriptions/api/v1` - URL: `https://api.ksamerchant.geidea.net/subscriptions/api/v1/direct/subscription` - Auth: HTTP basic This page will help you get started with Checkout - Subscription. ## Request body - object - `recurringPaymentAmount` number, float, required: Subscription amount ex: 100.00 - `currency` 'EGP' | 'SAR' | 'USD' | 'EUR', required: The currency of the payment. This is a 3-digit alphabetic code, following the ISO 4217 currency code standard. For example: AED - `cycleInterval` 'day' | 'week' | 'month' | 'year', required: Frequency for which a subscription transaction must be executed. - `cycleFrequency` integer, required: Number of times the subscription must be executed 1, 2, etc... - `typeOfPayment` 'RecurringLink' | 'RecurringPayment', required: Indicates type of Recurring Payment. RecurringPayment: means subsequent payment will be auto-collected from the customer based on his first payment RecurringLink: means a payment link will be sent to the customer based on the cycle interval and frequency. The customer needs to be present every time to pay If you are using Geidea Session or direct API's then you can pass typeOfPayment" = 'RecurringPayment"& "isFirstPmtPBL":false and collect the first payment from the customer via HPP. The subsequent payments will be auto-collected from the customer based on the scheduled job - `customerId` string: If you have already created a customer using the customerRequest object, you can pass it here. One of customerRequest Object or customerId is mandatory. - `customerRequest` object: Details of the customer required to create a customer. Once a customer is created you can send the customer Id in all future subscription requests. One of customerRequest Object or customerId is mandatory. - `name` string: Customer Name - `email` string: Email of customer. One of email or phoneNumber must be present. - `phoneCountryCode` string: Country code of customer's phone number eg: "+971". If phoneNumber is passed, phoneCountryCode must be passed. - `phone` string: Customer's phone number eg: "511111111". If phoneCountryCode is passed, phoneNumber must be passed. One of email or phoneNumber must be present. - `number` string - `description` string: The description of the subscription ex: TV channel plan A - `startDate` string: Start date of subscription. Ex: "2024-03-05T09:26:07.472Z" - `endDate` string: The end date of the subscription. For creating an endless subscription do not pass the endDate. For creating a subscription for a specific period, pass the endDate or numberOfPayments - `numberOfPayments` string: The number of payments for the subscription. For creating an endless subscription do not pass the endDate. For creating a subscription for a specific period, pass the endDate or numberOfPayments - `language` 'en' | 'ar': The language to be used on the checkout page. - `isFirstPmtPBL` boolean: Use this parameter as with value `true` or `false` depending upon how you would like to collect the first payment. If you pass this as `true` the customer will receive the first payment request as a payment link. If you are using Geidea Session or direct API's please pass the value as false. Default value will be true - `paylinkExpirationPeriod` string: The payment link expiration date, is required only when the isFirstPmtPBL parameter is set to true. The default expiration period for the payment link is 7 days. If you want to use any cycle frequency less than 7 days, please make sure you are passing the expiration period accordingly. - `timestamp` string: The timestamp of the moment at which the create subscription request has been initiated. - `signature` string, required: A parameter to ensure the security and authenticity of API communications. It involves generating a signature using the contents of the API request and secret keys, which is then sent along with the request. - `AmountVariability` 'VARIABLE' | 'FIXED': Indicates whether the subscription amount is fixed or changing during the subscription. If value is "FIXED" then the amount does not change during the subscription. If the value is "VARIABLE" then amount can be changed for the subscription. Note: If "FIXED" is used then "currency", "recurringPaymentAmount" and "cycleFrequency" can't be updated ## Response `200` 200 - object - `subscription` object - `customerName` string - `customerEmail` string - `customerPhoneCountryCode` string - `customerPhone` string - `customerAddresses` unknown[] - unknown - `subscriptionId` string - `merchantId` string - `merchantPublicKey` string - `description` string - `recurringPaymentAmount` integer - `currency` string - `initialPaymentAmount` unknown - `initialPaymentExpirationPeriod` unknown - `startDate` string - `endDate` string - `cycleInterval` string - `cycleFrequency` integer - `occurrences` object[] - `occurrenceId` string - `subscriptionId` string - `type` string - `amount` integer - `date` string - `status` string - `retries` unknown[] - unknown - `paylinkId` unknown - `orderId` unknown - `isInFinalStatus` boolean - `nextOccurrenceDate` string - `status` string - `typeOfPayment` string - `paylinkExpirationPeriod` integer - `numberOfPayments` unknown - `customerId` string - `number` string - `language` string - `agreementId` unknown - `merchantName` string - `amountVariability` string - `applePayRecurringToken` unknown - `isFirstPmtPBL` boolean - `createdDate` string - `createdBy` string - `updatedDate` string - `updatedBy` unknown - `responseCode` string - `detailedResponseCode` string ## Other responses - `400`: 400 --- [API](https://skmtc.dev/geidea/apis/subscriptions-v2.md) - [All operations](https://skmtc.dev/geidea/apis/subscriptions-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/geidea/apis/subscriptions-v2/revisions/f92595fd6949?raw)