Vendasta Order Fulfillment Forms API

openapi: 3.2.0
info:
  title: Platform REST Order Fulfillment Forms API
  version: Evergreen
servers:
- url: https://prod.apigateway.co/platform
  description: Production
- description: Demo
  url: https://demo.apigateway.co/platform
- description: Local
  url: '{local}/platform'
- url: http://localhost:11001/platform
  description: Localhost
tags:
- name: Order Fulfillment Forms
paths:
  /orderFulfillmentForms:
    get:
      summary: List Fulfillment Forms for an Order
      operationId: get-orderFulfillmentForms
      parameters:
      - schema:
          type: string
          example: AG-1234:ORD-1234567
        in: query
        name: ordersID
        required: true
        description: The composite order ID in the form `businessId:orderId`.
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/orderFulfillmentForms'
              examples:
                List fulfillment forms:
                  value:
                    data:
                    - id: AG-1234:ORD-1234567:MP-abc
                      type: orderFulfillmentForms
                      attributes:
                        appId: MP-abc
                        status: detailsNeeded
                        fields:
                        - id: target_keywords
                          value: ''
                          label: Target Keywords
                          description: Keywords you want to rank for
                          type: textarea
                        - id: business_hours
                          value: Mon-Fri 9am-5pm
                          label: Business Hours
                          type: text
                    - id: AG-1234:ORD-1234567:MP-xyz
                      type: orderFulfillmentForms
                      attributes:
                        appId: MP-xyz
                        status: inReview
                        fields:
                        - id: logo_file
                          value: https://example.com/logo.png
                          label: Logo
                          type: file
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Returns all fulfillment form submissions for the apps in a given order. Each app with a fulfillment order will have its own entry.'
      security:
      - OAuth2Demo:
        - order
        - order:read
      - OAuth2Prod:
        - order
        - order:read
      x-lifecycle:
        status: trustedTester
      tags:
      - Order Fulfillment Forms
    options:
      summary: List valid HTTP verbs for /orderFulfillmentForms
      operationId: options-orderFulfillmentForms
      responses:
        '204':
          description: No Content
      description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
      tags:
      - Order Fulfillment Forms
  /orderFulfillmentForms/{id}:
    parameters:
    - schema:
        type: string
      name: id
      in: path
      required: true
      example: AG-1234:ORD-1234567:MP-abc
      description: The composite fulfillment form ID in the form `businessId:orderId:appId`.
    get:
      summary: Get Fulfillment Form by ID
      operationId: get-orderFulfillmentForms-by-id
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/orderFulfillmentForms'
              examples:
                Fulfillment form in detailsNeeded status:
                  value:
                    data:
                      id: AG-1234:ORD-1234567:MP-abc
                      type: orderFulfillmentForms
                      attributes:
                        appId: MP-abc
                        status: detailsNeeded
                        fields:
                        - id: target_keywords
                          value: ''
                          label: Target Keywords
                          description: Keywords you want to rank for
                          type: textarea
                        - id: business_hours
                          value: Mon-Fri 9am-5pm
                          label: Business Hours
                          type: text
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Returns the latest fulfillment form submission for a specific app within an order.'
      security:
      - OAuth2Demo:
        - order
        - order:read
      - OAuth2Prod:
        - order
        - order:read
      x-lifecycle:
        status: trustedTester
      tags:
      - Order Fulfillment Forms
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
    patch:
      summary: Update Fulfillment Form
      operationId: patch-orderFulfillmentForms-by-id
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/orderFulfillmentForms'
              required:
              - data
            examples:
              Save form field data:
                value:
                  data:
                    id: AG-1234:ORD-1234567:MP-abc
                    type: orderFulfillmentForms
                    attributes:
                      fields:
                      - id: target_keywords
                        value: plumber, emergency plumber
                      - id: business_hours
                        value: Mon-Fri 9am-5pm
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/orderFulfillmentForms'
              examples:
                Updated fulfillment form:
                  value:
                    data:
                      id: AG-1234:ORD-1234567:MP-abc
                      type: orderFulfillmentForms
                      attributes:
                        appId: MP-abc
                        status: detailsNeeded
                        fields:
                        - id: target_keywords
                          value: plumber, emergency plumber
                          label: Target Keywords
                          description: Keywords you want to rank for
                          type: textarea
                        - id: business_hours
                          value: Mon-Fri 9am-5pm
                          label: Business Hours
                          type: text
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Saves (upserts) form field data for a specific app within an order.


        **Auto-submission:** When all required fields are filled, the fulfillment order status will automatically transition from `detailsNeeded` to `inReview` asynchronously — notifying the vendor without any additional API call. For most use cases this is sufficient and the `/actions/submit` endpoint is not needed.


        **Explicit submission:** If you need a synchronous status transition, or want to force `inReview` before all required fields are filled, use the `/orderFulfillmentForms/{id}/actions/submit` endpoint instead.'
      security:
      - OAuth2Demo:
        - order
      - OAuth2Prod:
        - order
      x-lifecycle:
        status: trustedTester
      tags:
      - Order Fulfillment Forms
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      - schema:
          type: string
          default: application/vnd.api+json
          enum:
          - application/vnd.api+json
        in: header
        name: Content-Type
        required: true
        description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
    options:
      summary: List valid HTTP verbs for /orderFulfillmentForms/{id}
      operationId: options-orderFulfillmentForms-by-id
      responses:
        '204':
          description: No Content
      description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
      tags:
      - Order Fulfillment Forms
  /orderFulfillmentForms/{id}/actions/submit:
    parameters:
    - schema:
        type: string
        example: AG-1234:ORD-1234567:MP-abc
      name: id
      in: path
      required: true
      description: Composite ID in the form `businessId:orderId:appId`.
    post:
      summary: Submit a fulfillment form to the vendor
      operationId: post-orderFulfillmentForms-submit
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Explicitly sets the fulfillment order status to `inReview`, notifying the vendor that the form is ready for processing.


        **Note:** In most cases you do not need to call this endpoint. When all required fields are filled via PATCH, the status automatically transitions to `inReview` asynchronously. Use this endpoint only when you need a synchronous transition, or want to force submission before all required fields are filled.


        The request body is optional. If `fields` are provided, they will be saved before the status transition occurs. If the fields were already saved via PATCH, the body can be omitted.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: array
                  description: Optional form fields to save before submitting.
                  items:
                    $ref: '#/components/schemas/orderFormField'
            examples:
              Submit with final field values:
                value:
                  fields:
                  - id: target_keywords
                    value: plumber, emergency plumber
                  - id: business_hours
                    value: Mon-Fri 9am-5pm
              Submit without fields (already saved via PATCH):
                value: {}
      responses:
        '204':
          description: No Content — form submitted successfully.
        '404':
          description: Not Found — the fulfillment order was not found for the given ID.
      security:
      - OAuth2Demo:
        - order
      - OAuth2Prod:
        - order
      x-lifecycle:
        status: trustedTester
      tags:
      - Order Fulfillment Forms
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
components:
  schemas:
    orderFormField:
      title: Order Form Field
      type: object
      description: A single field within an order form.
      properties:
        id:
          type: string
          description: The unique identifier of the field within its form.
          example: business_name
        value:
          type: string
          description: 'The answer or value for this field.


            For `file` fields, provide a plain URL string pointing to any publicly accessible file. The filename will be derived from the URL path. To use Vendasta-hosted file storage, first upload the file to `https://order-fulfillment-api-prod.apigateway.co/fulfillment-form/attachments/upload` and use the returned URL as the value.'
          example: Acme Corp
        label:
          type: string
          readOnly: true
          description: Human-readable label for the field. Read-only; returned on GET but ignored on create/update.
        description:
          type: string
          readOnly: true
          description: Description or help text for the field. Read-only.
        type:
          type: string
          description: The input type of the field. Required when creating or updating order forms.
          enum:
          - text
          - textarea
          - dropdown
          - checkbox
          - file
          - vbcUser
      required:
      - id
      - value
    orderFulfillmentForms:
      title: Order Fulfillment Form
      type: object
      x-lifecycle:
        status: trustedTester
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        A fulfillment form submission for an app within an order. Fulfillment forms are filled out after order creation to provide the vendor with information needed to fulfill the order.

        The ID is a composite of `businessId:orderId:appId`.


        **Workflow:** Use PATCH to save form field data as a draft, then POST to `/actions/submit` to explicitly submit the form to the vendor. The `status` field is read-only and reflects the vendor-side workflow state.


        **Limitation:** If an order contains multiple instances of the same add-on app, only a single set of form answers is stored per app ID. Per-instance form answers are not currently supported.'
      properties:
        id:
          type: string
          example: AG-1234:ORD-1234567:MP-abc
          readOnly: true
        type:
          type: string
          default: orderFulfillmentForms
          enum:
          - orderFulfillmentForms
        attributes:
          type: object
          properties:
            appId:
              type: string
              readOnly: true
              description: The app ID this fulfillment form belongs to.
              example: MP-abc
            status:
              type: string
              readOnly: true
              description: 'The current fulfillment order status. This field is read-only and reflects the vendor-side workflow state.


                - `detailsNeeded` — The vendor is waiting for the partner to provide form details.

                - `inReview` — The form has been submitted and is awaiting vendor review.

                - `inProgress` — The vendor is actively fulfilling the order.

                - `completed` — Fulfillment is complete.

                - `cancelled` — The fulfillment order was cancelled.

                - `onHold` — The fulfillment order is on hold.


                To submit a form (transitioning status to `inReview`), use the `/orderFulfillmentForms/{id}/actions/submit` endpoint.'
              enum:
              - detailsNeeded
              - inReview
              - inProgress
              - completed
              - cancelled
              - onHold
              example: detailsNeeded
            fields:
              type: array
              description: The form fields and their submitted values.
              items:
                $ref: '#/components/schemas/orderFormField'
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
    OAuth2Demo:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://sso-api-demo.apigateway.co/oauth2/auth
          tokenUrl: https://sso-api-demo.apigateway.co/oauth2/token
          scopes:
            sales.contact: Read-write access to sales contact details
            business:read: Read only access to business details
            business: Read-write access to business details
            partner:read: Read-write access to details about your partner
            financial: Read-write access to financial details
            order: Read-write access to order details
            order:read: Read only access to order details
            user.profile:read: Read access to the profile fields of all categories of users
            user.contact:read: Read access to the contact info (email, phone, address) of all categories of users
            user.permission:read: Read access to the permission info (accessible locations, features and roles) of all categories of users
            user.permission: Read-write access to the permission info (accessible locations, features and roles) of all categories of users
            user.admin: Read-write access to manage all users
            user.list: '''Allows searching for users based on a set of filters. (ex: email, name, category, organization). Without this scope an exact user id is required.'
            self.user.admin: Allows editing the profile, contact info and profile image for the current user.
            self.user.contact:read: Read access to the contact info (email, phone, address) of the current user.
            openid: Allows getting the user id of the current user
            profile: Readonly access to the user profile, including name, locale, and language preferences.
            email: Allows readonly access to the email of the current user.
            phone: Allows readonly access to the phone numbers of the current user.
            address: Allows readonly access to the address of the current user.
            sales.account: Allows read-write access to account records
            sales.proposals: Allows read-write access to proposals
            product: Read access to the product details
            automation:read: Read only access to automations
          refreshUrl: ''
    OAuth2Prod:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://sso-api-prod.apigateway.co/oauth2/auth
          tokenUrl: https://sso-api-prod.apigateway.co/oauth2/token
          scopes:
            sales.contact: Read-write access to sales contact details
            business:read: Read only access to business details
            business: Read-write access to business details
            partner:read: Read-write access to details about your partner
            financial: Read-write access to financial details
            order:read: Read only access to order details
            order: Read-write access to order details
            user.profile:read: Read access to the profile fields of all categories of users
            user.contact:read: Read access to the contact info (email, phone, address) of all categories of users
            user.permission:read: Read access to the permission info (accessible locations, features and roles) of all categories of users
            user.permission: Read-write access to the permission info (accessible locations, features and roles) of all categories of users
            user.admin: Read-write access to manage all users
            user.list: '''Allows searching for users based on a set of filters. (ex: email, name, category, organization). Without this scope an exact user id is required.'
            self.user.admin: Allows editing the profile, contact info and profile image for the current user.
            self.user.contact:read: Read access to the contact info (email, phone, address) of the current user.
            openid: Allows getting the user id of the current user
            profile: Readonly access to the user profile, including name, locale, and language preferences.
            email: Allows readonly access to the email of the current user.
            phone: Allows readonly access to the phone numbers of the current user.
            address: Allows readonly access to the address of the current user.
            sales.account: Allows read-write access to account records
            sales.proposals: Allows read-write access to proposals
            product: Read access to the product details
            automation:read: Read only access to automations
          refreshUrl: ''