> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.
# Create an offer
> Create a new offer
Required permissions: `offer:write`
## OpenAPI
````yaml post /subscriptions/{id}/offers
openapi: 3.1.0
info:
title: Fynn API
description: ''
termsOfService: https://www.fynn.eu/tos
contact:
name: Fynn UG (haftungsbeschränkt)
url: https://www.fynn.eu
email: hi@fynn.eu
license:
name: Proprietary
url: https://www.fynn.eu/license
version: 0.0.0
servers:
- url: https://coreapi.io
description: Production
- url: https://preview.coreapi.io
description: Sandbox
security:
- JWT: []
tags: []
paths:
/subscriptions/{id}/offers:
parameters: []
post:
tags:
- Offer
summary: Create an offer
description: |-
Create a new offer
Required permissions: `offer:write`
operationId: api_subscriptions_idoffers_post
parameters:
- name: id
in: path
description: Offer identifier
required: true
deprecated: false
schema:
type: string
style: simple
explode: false
requestBody:
description: The new Offer resource
content:
application/json:
schema:
$ref: '#/components/schemas/Offer.CreateOfferInput'
text/html:
schema:
$ref: '#/components/schemas/Offer.CreateOfferInput'
required: true
responses:
'201':
description: Offer resource created
content:
application/json:
schema:
$ref: '#/components/schemas/Offer-OfferDetail'
text/html:
schema:
$ref: '#/components/schemas/Offer-OfferDetail'
links: {}
'400':
description: Invalid input
'422':
description: Unprocessable entity
deprecated: false
security:
- JWT:
- offer:write
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl -X POST \
/subscriptions/{id}/offers \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"offerTemplateId": "",
"title": "",
"contactPerson": ""
}'
components:
schemas:
Offer.CreateOfferInput:
type: object
description: ''
deprecated: false
properties:
offerTemplateId:
type:
- string
- 'null'
title:
description: The title of the offer
type:
- string
- 'null'
crmMetadata:
description: >-
Metadata to create a deal in the CRM. This is only available if a
CRM is connected.
anyOf:
- $ref: '#/components/schemas/OfferCrmMetadata'
- type: 'null'
contactPerson:
description: The contact person for the offer
type:
- string
- 'null'
Offer-OfferDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
subscription:
anyOf:
- $ref: '#/components/schemas/Subscription-OfferDetail'
- type: 'null'
customer:
readOnly: true
anyOf:
- $ref: '#/components/schemas/Customer-OfferDetail'
- type: 'null'
number:
type: string
name:
type:
- string
- 'null'
status:
readOnly: true
type: string
enum:
- open
- signed
- signing
- archived
description:
type:
- string
- 'null'
sections:
type: array
items:
type: string
locale:
readOnly: true
type: string
recipients:
readOnly: true
type: array
items:
$ref: '#/components/schemas/OfferRecipient-OfferDetail'
auditLogDocument:
readOnly: true
anyOf:
- $ref: '#/components/schemas/Media-OfferDetail'
- type: 'null'
signedDocument:
readOnly: true
anyOf:
- $ref: '#/components/schemas/Media-OfferDetail'
- type: 'null'
signedAt:
readOnly: true
type:
- string
- 'null'
format: date-time
autoActivateSubscription:
default: true
example: true
type: boolean
crmDealId:
readOnly: true
type:
- string
- 'null'
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
contactPerson:
readOnly: true
description: The contact person of the offer
anyOf:
- $ref: '#/components/schemas/ContactPerson-OfferDetail'
- type: 'null'
OfferCrmMetadata:
type: object
description: ''
deprecated: false
properties:
contactId:
description: >-
Id of the contact in the CRM. This is used when creating a new deal
in the CRM.
type:
- string
- 'null'
companyId:
description: >-
Id of the company in the CRM. This is used when creating a new deal
in the CRM.
type:
- string
- 'null'
ownerId:
description: >-
Id of the owner in the CRM. This is used when creating a new deal in
the CRM.
type:
- string
- 'null'
priority:
description: >-
The priority of the deal. This is used when creating a new deal in
the CRM.
type:
- string
- 'null'
closingDate:
description: >-
The date the deal should be closed. This is used when updating a
deal in the CRM.
type:
- string
- 'null'
format: date-time
required:
- companyId
Subscription-OfferDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
externalId:
type:
- string
- 'null'
paymentMethod:
description: >-
The payment method of the subscription. If null, the default payment
method of the customer is used.
anyOf:
- $ref: '#/components/schemas/PaymentMethod-OfferDetail'
- type: 'null'
invoiceAddress:
description: >-
The invoice address of the subscription. If null, the default
invoice address of the customer is used.
anyOf:
- $ref: '#/components/schemas/CustomerAddress-OfferDetail'
- type: 'null'
number:
description: The number of the subscription.
example: S-00000001
type: string
customer:
$ref: '#/components/schemas/Customer-OfferDetail'
plan:
readOnly: true
description: The plan this subscription is based on.
anyOf:
- $ref: '#/components/schemas/Plan-OfferDetail'
- type: 'null'
name:
description: >-
The name of the subscription. Defaults to the name of the plan. This
will be used in the invoice for the grouping headers.
example: Fitness M
type:
- string
- 'null'
items:
description: The selected items of the subscription. Can be charges or addons.
type: array
items:
$ref: '#/components/schemas/SubscriptionItem-OfferDetail'
billingGroup:
description: The billing group defines the billing cycle of the subscription.
anyOf:
- $ref: '#/components/schemas/BillingGroup-OfferDetail'
- type: 'null'
periods:
type: array
items:
$ref: '#/components/schemas/TermPeriod-OfferDetail'
status:
readOnly: true
description: |-
The status of the subscription.
Possible values:
* `draft`: The subscription is in draft mode and not active yet.
* `active`: The subscription is active and will be billed.
* `paused`: The subscription is paused and will not be billed.
* `cancelled`: The subscription is cancelled and will not be billed anymore.
* `terminated`: The subscription is terminated and will not be billed anymore.
* `offer`: The subscription is an offer and waiting for acceptance.
example: active
activatedAt:
readOnly: true
description: The date the subscription was activated.
example: '2021-01-01T00:00:00+00:00'
type:
- string
- 'null'
format: date-time
poNumber:
description: The po number of the subscription.
example: PO-00000001
type:
- string
- 'null'
contractDetails:
$ref: '#/components/schemas/ContractDetails-OfferDetail'
description: The contract details of the subscription.
trialEndsOn:
readOnly: true
description: The date the trial period ends.
example: '2021-01-01T00:00:00+00:00'
type:
- string
- 'null'
format: date-time
customFields:
additionalProperties:
type: string
type:
- object
- 'null'
example:
field1: value1
field2: value2
description: >-
Custom fields for the entity. The keys are the field names and the
values are the field values. They need to be configured under
\"/custom-fields\" in the API documentation. The input is validated
against the configuration. For more details see [Custom Fields
Guide](/guide/tenant/custom-fields)
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
defaultPaymentMethod:
readOnly: true
description: >-
The payment method is null, we use the default payment method of the
customer.
type: boolean
defaultInvoiceAddress:
readOnly: true
description: >-
The invoice address is null, we use the default invoice address of
the customer.
type: boolean
nextBillingDate:
readOnly: true
description: The next billing date of the subscription.
type:
- string
- 'null'
format: date-time
lastBillingAt:
readOnly: true
description: The last billing date of the subscription.
type:
- string
- 'null'
format: date-time
cancellationDate:
readOnly: true
description: The date the subscription will be cancelled.
type:
- string
- 'null'
format: date-time
cancelledAt:
readOnly: true
description: The date when the subscription was cancelled.
type:
- string
- 'null'
format: date-time
cancellationReason:
readOnly: true
description: The reason why the subscription was cancelled.
anyOf:
- $ref: '#/components/schemas/CancellationReason-OfferDetail'
- type: 'null'
isCancellationPending:
readOnly: true
description: >-
Indicates if the subscription is pending for cancellation. If true,
the subscription will be cancelled in the future and the
cancellation could be revoked.
type: boolean
nextPossibleCancellationDate:
readOnly: true
type:
- array
- 'null'
items:
type: string
partner:
readOnly: true
description: The partner of the customer.
anyOf:
- $ref: '#/components/schemas/PartnerResource-OfferDetail'
- type: 'null'
Customer-OfferDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: 00000000-0000-0000-0000-000000000000
type: string
customerNumber:
minLength: 2
maxLength: 255
example: CUSTOMER-000
nullable: false
timeZone:
readOnly: true
default: Europe/Berlin
example: Europe/Berlin
type: string
firstName:
minLength: 2
maxLength: 255
description: Can be empty if the customer is a company.
example: John
nullable: true
lastName:
minLength: 2
maxLength: 255
description: Can be empty if the customer is a company.
example: Doe
nullable: true
currencyCode:
description: >-
Can be empty. In this case the default currency of the tenant is
used.
externalDocs:
url: https://schema.org/priceCurrency
example: EUR
type: string
companyName:
minLength: 2
maxLength: 255
example: Acme Inc.
type:
- string
- 'null'
datevId:
minLength: 2
maxLength: 255
description: The ID of the customer in DATEV
example: '123456789'
type:
- string
- 'null'
status:
default: STATUS_ACTIVE
example: STATUS_ACTIVE
enum:
- STATUS_ACTIVE
- STATUS_ARCHIVED
- STATUS_SUSPENDED
OfferRecipient-OfferDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
email:
type: string
firstName:
type: string
lastName:
type: string
role:
type: string
enum:
- read
- sign
createdAt:
readOnly: true
type: string
format: date-time
signingStatus:
readOnly: true
default: not_started
example: not_started
type: string
enum:
- pending
- started
- signed
- not_started
- archived
signingLog:
readOnly: true
type: array
items:
type: string
signedDocument:
readOnly: true
anyOf:
- $ref: '#/components/schemas/Media-OfferDetail'
- type: 'null'
link:
readOnly: true
description: Link to the offer for the recipient
example: https://example.com/offers/1/recipient-1
type: string
Media-OfferDetail:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/MediaId-OfferDetail'
readOnly: true
example: 01F9Z3ZJXZQZJZJZJZJZJZJZJZ
mimeType:
description: The mime type of the media
example: image/jpeg
type:
- string
- 'null'
fileExtension:
description: The file extension of the media
example: jpg
type: string
fileName:
description: The original file name of the media
example: invoice.jpg
type: string
ContactPerson-OfferDetail:
type: object
description: ''
deprecated: false
properties:
id:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
avatar:
type:
- string
- 'null'
phone:
type:
- string
- 'null'
linkedin:
type:
- string
- 'null'
position:
type:
- string
- 'null'
website:
type:
- string
- 'null'
PaymentMethod-OfferDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
description: Unique identifier of the payment method
example: c1a2b3c4-d5e6-4f7a-8b9b-0c1d2e3f4a5b
gatewayName:
type: string
enum:
- wallet
- sepa_debit
- stripe
- fake_provider
- paypal
- bank_transfer
- go_cardless
- testing
description: The payment gateway used to process the payment method
type:
type:
- string
- 'null'
enum:
- sepa_debit
- card
- paypal
- bank_transfer
- wallet
- fake_provider
- null
description: The type of the payment method
default:
type: boolean
description: Whether this is the default payment method for the customer
example: true
status:
default: active
example: active
type: string
enum:
- active
- action_required
- expired
- revoked
- gateway_unconfigured
description: The current status of the payment method
enabled:
type: boolean
description: Whether the payment method is enabled for use
example: true
name:
type:
- string
- 'null'
description: Display name of the payment method
example: Visa (4242)
creationDate:
readOnly: true
type: string
format: date-time
description: The date when the payment method was created
example: '2024-01-15T10:30:00+00:00'
expirationDate:
type:
- string
- 'null'
format: date-time
description: The expiration date of the payment method, if applicable
example: '2026-12-31T23:59:59+00:00'
card:
readOnly: true
description: The card data of the payment method, if the type is "card"
type: object
properties:
brand:
type: string
example: Visa
description: The brand of the card
last4:
type: string
example: '4242'
description: The last 4 digits of the card
expMonth:
type: integer
example: 12
description: The expiration month of the card
expYear:
type: integer
example: 2022
description: The expiration year of the card
cardHolder:
type: string
example: Max Mustermann
description: The card holder name
sepaDebit:
readOnly: true
description: >-
The sepa mandate data of the payment method, if the type is
"sepa_debit"
type: object
properties:
iban:
type: string
example: DE8937*********3232
description: The iban of the sepa mandate
bic:
type: string
example: COBADEFFXXX
description: The bic of the sepa mandate
mandateReference:
type: string
example: MNDT-2021-123456
description: The mandate reference of the sepa mandate
signingDate:
type: string
example: '2021-01-01T00:00:00+00:00'
description: The signing date of the sepa mandate
paypal:
readOnly: true
description: The paypal data of the payment method, if the type is "paypal"
type: object
properties:
email:
type: string
example: max@mustermann.de
description: The email of the paypal account
billingAgreementId:
type: string
example: I-1J5gqz2eZvKYlo2C2X2X2X2X
description: The billing agreement id of the paypal account
CustomerAddress-OfferDetail:
type: object
description: ''
deprecated: false
Plan-OfferDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: The unique identifier of the plan.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
family:
description: >-
Allow to group plans together. This allows to upgrade or downgrade
between plans in the same family.
anyOf:
- $ref: '#/components/schemas/PlanFamily-OfferDetail'
- type: 'null'
code:
description: >-
The code of the plan. This is used to identify the plan e.g. in the
checkout url.
example: basic-m2023
type: string
allowCheckout:
description: >-
Allow to checkout this plan. If this is set to false, the plan will
not be available in the checkout and can only be assigned to a
subscription by the API or in the admin panel. The plan.code is a
part of the checkout url.
default: true
example: true
type: boolean
status:
readOnly: true
description: |-
The status of the plan.
Possible values:
* `draft`: The plan is a draft and not available for usage in a subscription.
* `active`: The plan is active and can be used in a subscription.
* `archived`: The plan is archived and not longer available for usage in a subscription.
* `inactive`: The plan is inactive and not available for usage in a subscription.
default: draft
example: draft
changeBehaviour:
description: >-
Define the allowed actions after subscription by customer, for
upgrade / downgrade.
default: not_changeable
example: upgradeable_and_downgradeable
type: string
enum:
- upgradeable
- downgradeable
- upgradeable_and_downgradeable
- not_changeable
changeApplyBehaviour:
description: >-
Define the behaviour when a plan change will be applied. If null the
default behaviour will be used.
default: end_of_period
example: end_of_period
type: string
enum:
- immediately
- end_of_period
SubscriptionItem-OfferDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: 01F9ZQZJZJQZJZJZJZJZJZJZJZ
type: string
name:
readOnly: true
description: >-
The name of the item which will be used in the invoice. The name is
translated based on the customer's locale.
example: Fitness M
type: string
description:
readOnly: true
description: >-
The description of the item which will be used in the invoice. The
description is translated based on the customer's locale.
example: Everything included
type:
- string
- 'null'
furtherInformation:
readOnly: true
description: >-
Further information defines additional information for the item
which will be displayed in the invoice.
example: 'Additional agreements: The contract includes a free drink flatrate.'
type:
- string
- 'null'
status:
readOnly: true
description: |-
The status of the item.
Possible values:
* `active`: The item is active and will be billed.
* `canceled`: The item is canceled and will be billed until the end of the contract.
* `pending`: The item is pending and will be billed after the contract start.
* `terminated`: The item is terminated and will not be billed.
example: active
enum:
- active
- canceled
- pending
- terminated
subscriptionId:
readOnly: true
type: string
BillingGroup-OfferDetail:
type: object
description: ''
deprecated: false
TermPeriod-OfferDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
contractPeriodCount:
readOnly: true
type: integer
contractPeriod:
$ref: '#/components/schemas/Interval-OfferDetail'
readOnly: true
cancellationPeriod:
$ref: '#/components/schemas/Interval-OfferDetail'
readOnly: true
createdAt:
readOnly: true
type: string
format: date-time
updatedAt:
readOnly: true
type: string
format: date-time
ContractDetails-OfferDetail:
type: object
description: ''
deprecated: false
properties:
contractStart:
description: The start of the contract.
type: string
format: date-time
contractEnd:
description: The end of the contract.
type:
- string
- 'null'
format: date-time
CancellationReason-OfferDetail:
type: object
description: ''
deprecated: false
properties:
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
PartnerResource-OfferDetail:
type: object
description: ''
deprecated: false
properties:
id:
description: The ID of the partner
example: ad8f7e7d-3b3b-4b3b-8b3b-3b3b3b3b3b3b
type: string
name:
description: The name of the partner
example: John Doe
type: string
number:
description: The customer number of the partner
example: '123456'
type: string
email:
description: The email address of the partner
example: partner@example.com
type:
- string
- 'null'
MediaId-OfferDetail:
type: object
description: ''
deprecated: false
PlanFamily-OfferDetail:
type: object
description: ''
deprecated: false
properties:
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
Interval-OfferDetail:
type: object
description: ''
deprecated: false
securitySchemes:
JWT:
type: http
scheme: bearer
````