# Recurring Contracts ## POST /api/recurringProfile > Add a recurring profile ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/recurringProfile":{"post":{"tags":["Recurring Contracts"],"summary":"Add a recurring profile","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/AddRecurringProfileRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/AddRecurringProfileRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/AddRecurringProfileRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/AddRecurringProfileRequest"}}}},"responses":{"201":{"description":"Returns the newly created profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringProfileResponse"}}}},"400":{"description":"If it fails to create a profile","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"AddRecurringProfileRequest":{"required":["Amount","BillingFrequency","StartDate","TokenGuid"],"type":"object","properties":{"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"TokenGuid":{"type":"string","description":"required - Valid token guid of created tokenized account"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount to be charged per billing frequency"},"StartDate":{"type":"string","description":"required - format yyyy-MM-dd - start date of contract"},"EndDate":{"type":"string","description":"optional - format yyyy-MM-dd - end date of contract (must be after StartDate) if you wish a contract to stop recurring at certain date","nullable":true},"NextBillDate":{"type":"string","description":"optional - format yyyy-MM-dd - We will calculate if not provided. The date when the first recurrence should begin charging the donor's card. Must be after StartDate. Use our GET api/nextBillDate API to help calculate.","nullable":true},"BillingFrequency":{"type":"string","description":"required - How often the recurrence should occur. Possible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)"},"PreFeeAmount":{"maxLength":7,"type":"string","description":"optional - Pre Fee Amount with the fees not included if using PayFee flag (primary used for Non Profit transactions like Donations)","nullable":true},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction (primary used for Non Profit transactions like a donation), if used see Amount and PreFeeAmount info","nullable":true},"TransactionSourceGroupId":{"type":"string","description":"optional - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;","nullable":true},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional - Event Id per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional - Event Name per Product","nullable":true},"Surcharge":{"maxLength":7,"type":"string","description":"optional - calculated surcharge amount","nullable":true},"CommissionRateOverride":{"type":"string","description":"optional - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract. Primary used for Non Profit transactions.","nullable":true},"CardProcessingFeeOverride":{"type":"string","description":"optional - Overrides the default percentage processing fee. Primary used for Non Profit transactions.","nullable":true}},"additionalProperties":false,"description":""},"RecurringProfileResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"For all success responses, this will be True."},"Message":{"type":"string","description":"Recurring Profile response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Recurring Profile processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and will be null","nullable":true},"RecurringProfileGuid":{"type":"string","description":"GUID that identifies this particular recurring billing contract. This value is used for both the Update Recurring Profile and Cancel Recurring Profile endpoints.","format":"uuid"},"RecurringProfileId":{"type":"integer","description":"An integer identifier for this particular recurring billing contract. Is not used elsewhere in the API.","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## PUT /api/recurringProfile > Update a recurring profile ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/recurringProfile":{"put":{"tags":["Recurring Contracts"],"summary":"Update a recurring profile","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/UpdateRecurringProfileRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRecurringProfileRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/UpdateRecurringProfileRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/UpdateRecurringProfileRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringProfileResponse"}}}},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"UpdateRecurringProfileRequest":{"required":["RecurringProfileGuid"],"type":"object","properties":{"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"RecurringProfileGuid":{"type":"string","description":"required - Valid Recurring Profile Guid for update"},"Amount":{"maxLength":7,"type":"string","description":"optional if updating existing recurring profile - Amount to be charged per billing frequency","nullable":true},"StartDate":{"type":"string","description":"optional if updating existing recurring profile - format yyyy-MM-dd - start date of contract to update","nullable":true},"EndDate":{"type":"string","description":"optional if updating existing recurring profile - format yyyy-MM-dd - end date of contract (must be after StartDate) if you wish a contract to stop recurring at certain date","nullable":true},"NextBillDate":{"type":"string","description":"optional if updating existing recurring profile - format yyyy-MM-dd - The date when the first recurrence should begin charging the donor's card. Must be after StartDate.","nullable":true},"BillingFrequency":{"type":"string","description":"optional if updating existing recurring profile - How often the recurrence should occur. Possible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)","nullable":true},"PreFeeAmount":{"maxLength":7,"type":"string","description":"optional if updating existing recurring profile - Pre Fee Amount with the fees not included if using fee (used for Non Profit transactions like a donation)","nullable":true},"PayFee":{"type":"boolean","description":"optional if updating existing recurring profile - cover the fees flag for the transaction (primary used for Non Profit transactions like a donation), if used see Amount and PreFeeAmount info","nullable":true},"TransactionSourceGroupId":{"type":"string","description":"optional if updating existing recurring profile - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;","nullable":true},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional - Event Id per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional - Event Name per Product","nullable":true},"UseOriginalFees":{"type":"boolean","description":"optional - if a Non Profit organization has changed fees then UseOriginalFee = false will update recurring profile to use updated organization fees. Primary used for Non Profit transactions.","nullable":true},"CommissionRateOverride":{"type":"string","description":"optional - update the percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract. Primary used for Non Profit transactions.","nullable":true},"CardProcessingFeeOverride":{"type":"string","description":"optional - update the CardProcessingFeeOverride that Overrides the default percentage processing fee. Primary used for Non Profit transactions.","nullable":true}},"additionalProperties":false,"description":""},"RecurringProfileResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"For all success responses, this will be True."},"Message":{"type":"string","description":"Recurring Profile response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Recurring Profile processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and will be null","nullable":true},"RecurringProfileGuid":{"type":"string","description":"GUID that identifies this particular recurring billing contract. This value is used for both the Update Recurring Profile and Cancel Recurring Profile endpoints.","format":"uuid"},"RecurringProfileId":{"type":"integer","description":"An integer identifier for this particular recurring billing contract. Is not used elsewhere in the API.","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## DELETE /api/recurringProfile > Delete/Cancel a recurring profile ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/recurringProfile":{"delete":{"tags":["Recurring Contracts"],"summary":"Delete/Cancel a recurring profile","description":"","parameters":[{"name":"IntegrationSource","in":"query","description":"internal use - Identifies integrated Product","schema":{"type":"string"}},{"name":"RecurringProfileGuid","in":"query","description":"required - Valid Recurring Profile Guid for delete","required":true,"schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringProfileResponse"}}}},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"RecurringProfileResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"For all success responses, this will be True."},"Message":{"type":"string","description":"Recurring Profile response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Recurring Profile processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and will be null","nullable":true},"RecurringProfileGuid":{"type":"string","description":"GUID that identifies this particular recurring billing contract. This value is used for both the Update Recurring Profile and Cancel Recurring Profile endpoints.","format":"uuid"},"RecurringProfileId":{"type":"integer","description":"An integer identifier for this particular recurring billing contract. Is not used elsewhere in the API.","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## GET /api/nextBillDate > Get a next bill date calculated using Date and Billing Frequency from request for your recurring contract ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/nextBillDate":{"get":{"tags":["Recurring Contracts"],"summary":"Get a next bill date calculated using Date and Billing Frequency from request for your recurring contract","description":"","parameters":[{"name":"Date","in":"query","description":"required - format yyyy-MM-dd - Used to help calculate and return NextBillDate based on your Date provided.","required":true,"schema":{"type":"string"}},{"name":"BillingFrequency","in":"query","description":"required - How often the recurrence should occur. Used to help calculate NextBillDate based on billing frequency provided. Possible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)","required":true,"schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns next bill date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NextBillDateResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If the next bill date not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"NextBillDateResponse":{"type":"object","properties":{"NextBillDate":{"type":"string","description":"Response Format Example:\r\n\"NextBillDate\": \"2029-07-23TT00:00:00\"","format":"date-time"}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/recurring-contracts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.