Vendasta Sales Orders API
Sales Orders service and its auxiliary field schema, exposed through the gRPC gateway — the order surface behind the platform marketplace.
OpenAPI Specification
{
"components": {
"schemas": {
"LineItemAppKey": {
"properties": {
"appId": {
"type": "string"
},
"editionId": {
"type": "string"
},
"packageId": {
"description": "A package id is optional, it is used to group line items together in a package.",
"type": "string"
},
"packageInstanceId": {
"description": "A package instance id keeps track of the package instance that a line item belongs to. For example, if the customer purchases two packages that contain the same product,\nthis will identify which package the product belongs to.\n\nThis must be provided if a package id is provided, and should not be provided if there is no package id provided. The ID should be a uuid.",
"type": "string"
}
},
"type": "object"
},
"googlerpcStatus": {
"properties": {
"code": {
"format": "int32",
"type": "integer"
},
"details": {
"items": {
"$ref": "#/components/schemas/protobufAny"
},
"type": "array"
},
"message": {
"type": "string"
}
},
"type": "object"
},
"protobufAny": {
"additionalProperties": {},
"properties": {
"@type": {
"type": "string"
}
},
"type": "object"
},
"salesordersv1Status": {
"default": "SUBMITTED",
"description": "- SUBMITTED: Submitted is the status when an order is ready for admin approval\n - APPROVED: Approved is the status when an order is has been approved by an admin\n - DECLINED: Declined is the status when an order is has been declined by an admin or a smb\n - DRAFTED: Drafted is currently not used but would be the state the order can be created in before it's sent to someone else\n - FULFILLED: Fulfilled is the status when an order has had all of the products activated\n - PROCESSING: Processing is the status when an order is currently activating the products\n - ACTIVATION_ERRORS: ActivationErrors is the status when an order is has encountered an error when activating products\n - ARCHIVED: Archived is the status to use when hiding the orders from the ui unless explicitly asked for\n - SUBMITTED_FOR_CUSTOMER_APPROVAL: SubmittedForCustomerApproval is the status when an order has been sent to a SMB to approve\n - CANCELLATION_REQUESTED: CancellationRequested is the status when a sales person requests to cancel a full order\n - CANCELLED: Cancelled is the status when a after an admin has approved a Cancellation\n - SCHEDULED_ACTIVATION: ScheduledActivation is the status of an order after the admin requests to activate products on the contract start date\n - AWAITING_PAYMENT: AwaitingPayment is the status of a BIY order on creation before we attempt to charge\n - PROCESSING_PAYMENT: ProcessingPayment is the status of a BIY order while waiting on confirmation for the charge\n - RESUBMITTED: Resubmitted is the status of an order when it has been resubmitted for admin approval, after being submitted at least one other time in the past",
"enum": [
"SUBMITTED",
"APPROVED",
"DECLINED",
"DRAFTED",
"FULFILLED",
"PROCESSING",
"ACTIVATION_ERRORS",
"ARCHIVED",
"SUBMITTED_FOR_CUSTOMER_APPROVAL",
"CANCELLATION_REQUESTED",
"CANCELLED",
"SCHEDULED_ACTIVATION",
"AWAITING_PAYMENT",
"PROCESSING_PAYMENT",
"RESUBMITTED"
],
"title": "The different statuses representing any given state an order can be in",
"type": "string"
},
"salesv1Duration": {
"properties": {
"duration": {
"$ref": "#/components/schemas/v1DurationPeriod"
},
"value": {
"description": "Value for duration of time of a given operation.",
"format": "int64",
"type": "string"
}
},
"type": "object"
},
"v1ActivationStatus": {
"default": "PENDING",
"description": "- PENDING: The product is in the process of being activated\n - ACTIVATED: The product was successfully activated via the order\n - ERRORED: An error occured while activating the product during the activation step\n - ALREADY_ACTIVATED: The product was already active prior to fulfilling the order\n - IGNORED_ERRORS: An error occurred while activating the product during the activation step but then the item was marked as ignored errors\n - CANCELED: The product was requested to be deactivated at a time in the future (awaiting a deactivation date)\n - DEACTIVATED: The product has been deactivated/turned off\n - UNKNOWN: The product activation status is in an unknown status. Otherwise a client will inaccurately assume the default status is Pending.\n - SCHEDULED: The product activation has been scheduled\n - UNSCHEDULED: The product activation has been unscheduled",
"enum": [
"PENDING",
"ACTIVATED",
"ERRORED",
"ALREADY_ACTIVATED",
"IGNORED_ERRORS",
"CANCELED",
"DEACTIVATED",
"UNKNOWN",
"SCHEDULED",
"UNSCHEDULED"
],
"title": "The different statuses representing any given state that a product can be in during the activation process",
"type": "string"
},
"v1AddonActivation": {
"description": "A single addon and its corresponding activation status within an order.",
"properties": {
"activationStatus": {
"$ref": "#/components/schemas/v1ActivationStatus"
},
"addonId": {
"description": "Output only. Unique identifier of the addon that is going through the activation process.",
"readOnly": true,
"type": "string"
},
"appId": {
"description": "Output only. Unique identifier of the parent app for the addon.",
"readOnly": true,
"type": "string"
}
},
"title": "Addon Activation",
"type": "object"
},
"v1AddonKey": {
"properties": {
"addonId": {
"title": "Unique identifier of an addon",
"type": "string"
},
"appId": {
"title": "The parent app for the addon",
"type": "string"
}
},
"type": "object"
},
"v1Agreement": {
"description": "A terms of service agreement that a customer has accepted or declined on an order.",
"properties": {
"agreed": {
"description": "Required. Whether or not the user agreed.",
"type": "boolean"
},
"term": {
"description": "Required. The term that the user may have agreed to.",
"type": "string"
},
"userId": {
"description": "Required. The user who may have agreed to this agreement.",
"type": "string"
}
},
"required": [
"userId",
"term",
"agreed"
],
"title": "Agreement",
"type": "object"
},
"v1Attachment": {
"description": "A file attachment associated with an order.",
"properties": {
"name": {
"description": "Required. The name of the attachment.",
"type": "string"
},
"url": {
"description": "Required. The URL to the attachment.",
"type": "string"
}
},
"required": [
"name",
"url"
],
"title": "Attachment",
"type": "object"
},
"v1AuxiliaryDataFieldSchema": {
"properties": {
"archived": {
"format": "date-time",
"type": "string"
},
"created": {
"format": "date-time",
"type": "string"
},
"currencyCode": {
"title": "currency code according to ISO-4217, e.g. 'USD', 'CAD', 'BRL', etc",
"type": "string"
},
"dropdownOptions": {
"items": {
"$ref": "#/components/schemas/v1DropdownOption"
},
"type": "array"
},
"externalId": {
"type": "string"
},
"fieldDescription": {
"type": "string"
},
"fieldId": {
"type": "string"
},
"fieldName": {
"type": "string"
},
"fieldType": {
"$ref": "#/components/schemas/v1AuxiliaryDataFieldType"
},
"partnerId": {
"type": "string"
},
"updated": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"v1AuxiliaryDataFieldType": {
"default": "AUXILIARY_DATA_FIELD_TYPE_INVALID",
"enum": [
"AUXILIARY_DATA_FIELD_TYPE_INVALID",
"AUXILIARY_DATA_FIELD_TYPE_STRING",
"AUXILIARY_DATA_FIELD_TYPE_INTEGER",
"AUXILIARY_DATA_FIELD_TYPE_DATE",
"AUXILIARY_DATA_FIELD_TYPE_DROPDOWN",
"AUXILIARY_DATA_FIELD_TYPE_CURRENCY"
],
"type": "string"
},
"v1BillingPeriod": {
"properties": {
"duration": {
"$ref": "#/components/schemas/salesv1Duration"
},
"endDate": {
"format": "date-time",
"title": "The end date of the billing period",
"type": "string"
},
"startDate": {
"format": "date-time",
"title": "The start date of the billing period",
"type": "string"
}
},
"title": "The Time frame to bill for",
"type": "object"
},
"v1Business": {
"description": "Details about the business that an order is associated with.",
"properties": {
"address": {
"description": "Output only. The primary address of the business.",
"readOnly": true,
"type": "string"
},
"address2": {
"description": "Output only. The secondary address line of the business.",
"readOnly": true,
"type": "string"
},
"city": {
"description": "Output only. The city of the business.",
"readOnly": true,
"type": "string"
},
"companyName": {
"description": "Output only. The company name of the business.",
"readOnly": true,
"type": "string"
},
"country": {
"description": "Output only. The country of the business.",
"readOnly": true,
"type": "string"
},
"deleted": {
"description": "Output only. Whether the business has been deleted.",
"readOnly": true,
"type": "boolean"
},
"phoneNumber": {
"description": "Output only. The phone number of the business.",
"readOnly": true,
"type": "string"
},
"state": {
"description": "Output only. The state or province of the business.",
"readOnly": true,
"type": "string"
},
"website": {
"description": "Output only. The website URL of the business.",
"readOnly": true,
"type": "string"
},
"zip": {
"description": "Output only. The postal or zip code of the business.",
"readOnly": true,
"type": "string"
}
},
"title": "Business",
"type": "object"
},
"v1CommonField": {
"description": "A field answer that may be shared across multiple products or addons.",
"properties": {
"addonKeys": {
"description": "Optional. List of addon keys that share the common field.",
"items": {
"$ref": "#/components/schemas/v1AddonKey"
},
"type": "array"
},
"field": {
"$ref": "#/components/schemas/v1Field"
},
"productIds": {
"description": "Optional. List of unique product identifiers that share the common field.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Common Field",
"type": "object"
},
"v1Cost": {
"properties": {
"customPrice": {
"format": "int64",
"title": "The custom price of the order item. Can only be changed if the application supports custom pricing",
"type": "string"
}
},
"title": "Cost represents the wholesale cost of an order",
"type": "object"
},
"v1CreateSalesOrderRequest": {
"properties": {
"attachments": {
"items": {
"$ref": "#/components/schemas/v1Attachment"
},
"title": "Data for the attachments on the order",
"type": "array"
},
"businessId": {
"title": "ID of the business that the order is for",
"type": "string"
},
"commonFields": {
"items": {
"$ref": "#/components/schemas/v1CommonField"
},
"title": "A list of additional information that is shared across multiple products",
"type": "array"
},
"contractDuration": {
"$ref": "#/components/schemas/salesv1Duration"
},
"customFields": {
"items": {
"$ref": "#/components/schemas/v1CustomField"
},
"title": "A list of additional unique information pertaining to an individual product",
"type": "array"
},
"customerAttachments": {
"items": {
"$ref": "#/components/schemas/v1Attachment"
},
"title": "Data for the customer attachments on the order",
"type": "array"
},
"customerNotes": {
"title": "Additional notes written for customer by a salesperson",
"type": "string"
},
"enforceContractTerm": {
"title": "Indicates whether to enforce the contract term",
"type": "boolean"
},
"extraFields": {
"items": {
"$ref": "#/components/schemas/v1Field"
},
"title": "Extra fields are the fields that a partner (or market) admin has added to their orders by default to be filled",
"type": "array"
},
"idempotencyKey": {
"title": "Optional key used to prevent request duplication and allows safety when retrying requests",
"type": "string"
},
"lineItems": {
"items": {
"$ref": "#/components/schemas/v1LineItem"
},
"title": "Lineitems replace Products and Packages",
"type": "array"
},
"marketId": {
"title": "ID of the market that the order belongs to",
"type": "string"
},
"notes": {
"title": "Additional notes written by a salesperson for admin only",
"type": "string"
},
"opportunityIds": {
"items": {
"type": "string"
},
"title": "Opportunity id(s) that the order is fulfilling",
"type": "array"
},
"orderIsSmbPayable": {
"title": "Indicates whether the order should be charged to the SMB or not",
"type": "boolean"
},
"origin": {
"$ref": "#/components/schemas/v1Origin"
},
"packages": {
"items": {
"$ref": "#/components/schemas/v1Package"
},
"title": "Data for the package(s) being activated upon approval of this order",
"type": "array"
},
"partnerId": {
"title": "ID of the partner that the order belongs to",
"type": "string"
},
"products": {
"items": {
"$ref": "#/components/schemas/v1Product"
},
"title": "Data for the product(s) being activated upon approval of this order",
"type": "array"
},
"quoteId": {
"title": "ID of the quote associated with the order if the order was created from a quote",
"type": "string"
},
"requestedActivation": {
"format": "date-time",
"title": "Time submitted by a salesperson that indicates when an administrator should activate the products on the order",
"type": "string"
},
"salespersonId": {
"title": "ID of the salesperson who should attend to the order",
"type": "string"
},
"tags": {
"items": {
"type": "string"
},
"title": "Tags on the order",
"type": "array"
},
"useCustomerPrice": {
"title": "Indicates whether or not to automatically resolve the line items' retail pricing.\nThe request's line items are expected to have nil revenue if this is set to true.\nFor more information and error scenarios, see Confluence docs:\nhttps://vendasta.jira.com/wiki/spaces/PSYC/pages/2211971323/New+use+customer+price+on+sales-orders+Create+APIs",
"type": "boolean"
}
},
"title": "Containing information to create a new order",
"type": "object"
},
"v1CreateSalesOrderResponse": {
"properties": {
"orderId": {
"title": "Unique identifier of an order",
"type": "string"
}
},
"title": "Response of creating an order",
"type": "object"
},
"v1Currency": {
"default": "USD",
"description": "- ZAR: Do not add to this list. If more currencies are required currency_code should be used instead",
"enum": [
"USD",
"CAD",
"EUR",
"AUD",
"GBP",
"NZD",
"ZAR"
],
"type": "string"
},
"v1CustomField": {
"description": "A set of custom field answers that are unique to a specific product or addon.",
"properties": {
"addonKey": {
"$ref": "#/components/schemas/v1AddonKey"
},
"fields": {
"description": "Optional. List of custom fields for a given product.",
"items": {
"$ref": "#/components/schemas/v1Field"
},
"type": "array"
},
"productId": {
"description": "Optional. Unique identifier of the product that the custom questions belong to. Will not be provided if the custom field belongs to an addon.",
"type": "string"
}
},
"title": "Custom Field",
"type": "object"
},
"v1CustomPriceMapping": {
"properties": {
"customPrice": {
"format": "int64",
"title": "The custom price value of the product",
"type": "string"
},
"productId": {
"title": "The ID of the product",
"type": "string"
}
},
"title": "Representing custom prices for variable priced products in a package",
"type": "object"
},
"v1CustomerRecipient": {
"description": "Details about the customer who receives the order.",
"properties": {
"firstName": {
"description": "Output only. The user's first name.",
"readOnly": true,
"type": "string"
},
"lastName": {
"description": "Output only. The user's last name.",
"readOnly": true,
"type": "string"
},
"userId": {
"description": "Output only. The ID of the user.",
"readOnly": true,
"type": "string"
}
},
"title": "Customer Recipient",
"type": "object"
},
"v1DropdownOption": {
"properties": {
"label": {
"type": "string"
},
"value": {
"type": "string"
}
},
"type": "object"
},
"v1DurationPeriod": {
"default": "UNSPECIFIED",
"enum": [
"UNSPECIFIED",
"MONTH",
"YEAR",
"DAY",
"WEEK"
],
"type": "string"
},
"v1Field": {
"description": "An information field pertaining to a product, containing a question and its answer.",
"properties": {
"answer": {
"description": "Optional. Response related to the question of the field_id.",
"type": "string"
},
"description": {
"description": "Optional. The description of the field.",
"type": "string"
},
"fieldId": {
"description": "Required. Unique identifier of a custom or common field.",
"type": "string"
},
"fieldType": {
"$ref": "#/components/schemas/v1FieldType"
},
"label": {
"description": "Optional. The question for the custom or common field.",
"type": "string"
},
"prefix": {
"description": "Optional. For textbox fields, this string will be displayed in front of the textbox.",
"type": "string"
},
"regexErrorMessage": {
"description": "Optional. The error message displayed if the regex_validator does not match the answer.",
"type": "string"
},
"regexValidator": {
"description": "Optional. A regex string used to validate a field's answer.",
"type": "string"
},
"suffix": {
"description": "Optional. For textbox fields, this string will be displayed behind the textbox.",
"type": "string"
}
},
"required": [
"fieldId"
],
"title": "Field",
"type": "object"
},
"v1FieldSchemaIdentifier": {
"properties": {
"externalId": {
"type": "string"
},
"fieldId": {
"type": "string"
},
"partnerId": {
"type": "string"
}
},
"type": "object"
},
"v1FieldType": {
"default": "NOT_SPECIFIED",
"enum": [
"NOT_SPECIFIED",
"TEXT",
"TEXTAREA",
"DROPDOWN",
"CHECKBOX",
"FILE",
"VBCUSER"
],
"title": "Available types that a field can be",
"type": "string"
},
"v1FulfillmentOrderStatus": {
"default": "FULFILLMENT_STATUS_UNSET",
"description": " - FULFILLMENT_STATUS_DETAILS_NEEDED: Details Needed: Fulfillment Form needs to be submitted\n - FULFILLMENT_STATUS_IN_REVIEW: In Review: Fulfillment Form has been submitted. Vendor is reviewing submission\n - FULFILLMENT_STATUS_IN_PROGRESS: In Progress: Fulfillment Form has required info and work has begun to deliver order.\n - FULFILLMENT_STATUS_COMPLETED: Completed: Work for the order is done and has been delivered.\n - FULFILLMENT_STATUS_CANCELLED: Cancelled: Fulfillment has not been completed and will not be completed.",
"enum": [
"FULFILLMENT_STATUS_UNSET",
"FULFILLMENT_STATUS_DETAILS_NEEDED",
"FULFILLMENT_STATUS_IN_REVIEW",
"FULFILLMENT_STATUS_IN_PROGRESS",
"FULFILLMENT_STATUS_COMPLETED",
"FULFILLMENT_STATUS_CANCELLED"
],
"type": "string"
},
"v1GetAuxiliaryDataFieldSchemaRequest": {
"properties": {
"identifier": {
"$ref": "#/components/schemas/v1FieldSchemaIdentifier"
}
},
"type": "object"
},
"v1GetAuxiliaryDataFieldSchemaResponse": {
"properties": {
"fieldSchema": {
"$ref": "#/components/schemas/v1AuxiliaryDataFieldSchema"
}
},
"type": "object"
},
"v1GetSalesOrderRequest": {
"properties": {
"businessId": {
"title": "The business the order belongs to",
"type": "string"
},
"orderId": {
"title": "Unique identifier of an order",
"type": "string"
},
"projectionFilter": {
"$ref": "#/components/schemas/v1SalesOrderProjectionFilter"
}
},
"title": "Containing information to get an order",
"type": "object"
},
"v1GetSalesOrderResponse": {
"properties": {
"order": {
"$ref": "#/components/schemas/v1Order"
}
},
"title": "Response of getting an order",
"type": "object"
},
"v1LineItem": {
"properties": {
"appKey": {
"$ref": "#/components/schemas/LineItemAppKey"
},
"autoBillable": {
"title": "DEPRECATED: use non_billable instead",
"type": "boolean"
},
"billToRecipientId": {
"description": "The billing recipient for this line item.\nWhen set to a partner_id, wholesale billing applies (default behavior).\nWhen set to an account_group_id, retail billing is triggered for that customer.\nWhen empty, defaults to the merchant (partner) paying wholesale.",
"type": "string"
},
"billingPeriod": {
"$ref": "#/components/schemas/v1BillingPeriod"
},
"cost": {
"$ref": "#/components/schemas/v1Cost"
},
"currency": {
"$ref": "#/components/schemas/v1Currency"
},
"currencyCode": {
"description": "The 3-letter currency code defined in ISO 4217.",
"type": "string"
},
"currentRevenue": {
"$ref": "#/components/schemas/v1Revenue"
},
"customPrices": {
"items": {
"$ref": "#/components/schemas/v1CustomPriceMapping"
},
"title": "The custom price mapping for variable priced products in a package in the order",
"type": "array"
},
"initialRevenue": {
"$ref": "#/components/schemas/v1Revenue"
},
"isTrial": {
"title": "Only used when AppKey is the identifier",
"type": "boolean"
},
"nonBillable": {
"title": "Indicates whether this line item should be billable or not\nIf true, the item will not be billed",
"type": "boolean"
},
"packageId": {
"type": "string"
},
"quantity": {
"format": "int64",
"type": "string"
},
"retailSubscriptionGroupId": {
"title": "The retail subscription group id that this line item belongs to (if any)",
"type": "string"
},
"taxRateIds": {
"items": {
"type": "string"
},
"title": "The tax rate ids that apply to this line item",
"type": "array"
}
},
"type": "object"
},
"v1ListAuxiliaryDataFieldSchemaRequest": {
"properties": {
"filters": {
"$ref": "#/components/schemas/v1ListAuxiliaryDataFieldSchemaRequestFilters"
},
"pagingOptions": {
"$ref": "#/components/schemas/vendastatypesPagedRequestOptions"
},
"partnerId": {
"type": "string"
}
},
"type": "object"
},
"v1ListAuxiliaryDataFieldSchemaRequestFilters": {
"properties": {
"onlyArchived": {
"type": "boolean"
}
},
"type": "object"
},
"v1ListAuxiliaryDataFieldSchemaResponse": {
"properties": {
"fieldSchemas": {
"items": {
"$ref": "#/components/schemas/v1AuxiliaryDataFieldSchema"
},
"type": "array"
},
"pagingMetadata": {
"$ref": "#/components/schemas/vendastatypesPagedResponseMetadata"
}
},
"type": "object"
},
"v1ListSalesOrderRequest": {
"properties": {
"cursor": {
"title": "current cursor position",
"type": "string"
},
"filters": {
"$ref": "#/components/schemas/v1ListSalesOrderRequestFilters"
},
"pageSize": {
"format": "int64",
"title": "size of the page to list\n0 assumes the default page size",
"type": "string"
},
"partnerId": {
"title": "partner id for partner making request",
"type": "string"
},
"sortOption": {
"$ref": "#/components/schemas/v1ListSalesOrderRequestSortOption"
}
},
"title": "Request to get a list of orders for a partner",
"type": "object"
},
"v1ListSalesOrderRequestDateRangeFilter": {
"properties": {
"beginRange": {
"format": "date-time",
"type": "string"
},
"endRange": {
"format": "date-time",
"type": "string"
}
},
"title": "Begin and end of date range",
"type": "object"
},
"v1ListSalesOrderRequestFilters": {
"properties": {
"businessId": {
"title": "Singular business filter",
"type": "string"
},
"created": {
"$ref": "#/components/schemas/v1ListSalesOrderRequestDateRangeFilter"
},
"expiryDate": {
"$ref": "#/components/schemas/v1ListSalesOrderRequestDateRangeFilter"
},
"includeArchivedOrders": {
"title": "Will include archived orders if true",
"type": "boolean"
},
"marketId": {
"title": "DEPRECATED: Singular market filter. Use market_ids instead. If both are supplied, market_ids will be used instead",
"type": "string"
},
"marketIds": {
"items": {
"type": "string"
},
"title": "Multi market request",
"type": "array"
},
"orderId": {
"title": "DEPRECATED: Singular order identifier to filter for. Use order_ids instead. If both are supplied, order_ids will be used instead",
"type": "string"
},
"orderIds": {
"items": {
"type": "string"
},
"title": "Multiple order identifiers to filter for",
"type": "array"
},
"packageId": {
"title": "Singular package filter",
"type": "string"
},
"productEditionId": {
"title": "Singular product edition filter",
"type": "string"
},
"productId": {
"title": "Singular product filter",
"type": "string"
},
"requestedActivation": {
"$ref": "#/components/schemas/v1ListSalesOrderRequestDateRangeFilter"
},
"salespersonId": {
"title": "DEPRECATED: Singular salesperson filter. Use salesperson_ids instead. If both are supplied, salesperson_ids\nwill be used instead",
"type": "string"
},
"salespersonIds": {
"items": {
"type": "string"
},
"title": "Multiple salesperson filter",
"type": "array"
},
"statuses": {
"items": {
"$ref": "#/components/schemas/salesordersv1Status"
},
"title": "Multiple
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vendasta/refs/heads/main/openapi/vendasta-sales-orders-openapi.json