> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Execute an equipment order intent
> Carry out an equipment order intent: places its catalog order — a real purchase against its billing profile — hands over its stock items, sends the enrollment request when asked, links the order and devices to its task and completes the task. This is the only way to complete an EQUIPMENT_ORDER task: `updateTaskStatus` refuses it with `TaskLockedByTypeError` naming this operation. Safe to retry: an intent executed earlier answers `outcome: ALREADY_EXECUTED` and orders nothing again, and an order placed by an attempt that failed later is not placed twice. Refused with `TICKET_SCHEDULED` before a scheduled task wakes up, `TICKET_CLOSED`, `DUPLICATE_ORDER` (same products for the employee within 5 minutes), `EXECUTION_IN_PROGRESS`, `NOTHING_TO_EXECUTE`, `INVENTORY_ITEM_NOT_FOUND`, `INVENTORY_DEVICE_RETIRED`, `INVENTORY_ASSIGNMENT_FAILED`; a refusal leaves the task PENDING with an internal comment on the ticket. `executeOnboardingEquipment` is the legacy twin: use it only for an onboarding still on the classic Equipment step, which it closes. Use the equipment order intent for equipment work tracked as a task on a ticket (an EQUIPMENT_ORDER task) — it never closes an onboarding Equipment step.
Key: WriteScope: Company
## OpenAPI
````yaml https://api.getprimo.com/openapi.json post /equipment-order-intents/{intentId}/execute
openapi: 3.1.1
info:
title: Public API - BETA
description: Read docs on https://docs.getprimo.com/
version: '1.0'
contact: {}
servers:
- url: https://api.getprimo.com
security:
- apikey: []
tags: []
paths:
/equipment-order-intents/{intentId}/execute:
post:
tags:
- Orders
summary: Execute an equipment order intent
description: >-
Carry out an equipment order intent: places its catalog order — a real
purchase against its billing profile — hands over its stock items, sends
the enrollment request when asked, links the order and devices to its
task and completes the task. This is the only way to complete an
EQUIPMENT_ORDER task: `updateTaskStatus` refuses it with
`TaskLockedByTypeError` naming this operation. Safe to retry: an intent
executed earlier answers `outcome: ALREADY_EXECUTED` and orders nothing
again, and an order placed by an attempt that failed later is not placed
twice. Refused with `TICKET_SCHEDULED` before a scheduled task wakes up,
`TICKET_CLOSED`, `DUPLICATE_ORDER` (same products for the employee
within 5 minutes), `EXECUTION_IN_PROGRESS`, `NOTHING_TO_EXECUTE`,
`INVENTORY_ITEM_NOT_FOUND`, `INVENTORY_DEVICE_RETIRED`,
`INVENTORY_ASSIGNMENT_FAILED`; a refusal leaves the task PENDING with an
internal comment on the ticket. `executeOnboardingEquipment` is the
legacy twin: use it only for an onboarding still on the classic
Equipment step, which it closes. Use the equipment order intent for
equipment work tracked as a task on a ticket (an EQUIPMENT_ORDER task) —
it never closes an onboarding Equipment step.
operationId: executeEquipmentOrderIntent
parameters:
- name: intentId
required: true
in: path
schema:
type: string
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteEquipmentOrderIntentResult_Output'
components:
schemas:
ExecuteEquipmentOrderIntentResult_Output:
type: object
properties:
outcome:
type: string
description: >-
ALREADY_EXECUTED: an earlier call did the work — nothing was ordered
or assigned again
enum:
- EXECUTED
- ALREADY_EXECUTED
intent:
type: object
properties:
id:
type: string
description: >-
Intent id — pass it to `updateEquipmentOrderIntent` and
`executeEquipmentOrderIntent`
taskId:
description: The EQUIPMENT_ORDER task that tracks this order
anyOf:
- type: string
- type: 'null'
ticketId:
description: >-
The ticket holding that task: the parentTicketId sent, or the
one Primo opened. Null if it could not be read back.
anyOf:
- type: string
- type: 'null'
employeeId:
anyOf:
- type: string
- type: 'null'
order:
anyOf:
- type: object
properties:
countryCode:
description: Catalog country code (lowercase ISO 3166-1 alpha-2)
type: string
enum:
- af
- al
- dz
- ad
- ao
- ag
- ar
- am
- au
- at
- az
- bs
- bh
- bd
- bb
- by
- be
- bz
- bj
- bt
- bo
- ba
- bw
- br
- bn
- bg
- bf
- bi
- cv
- kh
- cm
- ca
- cf
- td
- cl
- cn
- co
- km
- cg
- cr
- hr
- cu
- cy
- cz
- cd
- dk
- dj
- dm
- do
- ec
- eg
- sv
- gq
- er
- ee
- sz
- et
- fj
- fi
- fr
- ga
- gm
- ge
- de
- gh
- gr
- gd
- gt
- gn
- gw
- gy
- ht
- hn
- hu
- is
- in
- id
- ir
- iq
- ie
- il
- it
- jm
- jp
- jo
- kz
- ke
- ki
- kw
- kg
- la
- lv
- lb
- ls
- lr
- ly
- li
- lt
- lu
- mg
- mw
- my
- mv
- ml
- mt
- mh
- mr
- mu
- mx
- fm
- md
- mc
- mn
- me
- ma
- mz
- mm
- na
- nr
- np
- nl
- nz
- ni
- ne
- ng
- kp
- mk
- 'no'
- om
- pk
- pw
- pa
- pg
- py
- pe
- ph
- pl
- pt
- qa
- ro
- ru
- rw
- kn
- lc
- vc
- ws
- sm
- st
- sa
- sn
- rs
- sc
- sl
- sg
- sk
- si
- sb
- so
- za
- kr
- ss
- es
- lk
- sd
- sr
- se
- ch
- sy
- tw
- tj
- tz
- th
- tl
- tg
- to
- tt
- tn
- tr
- tm
- tv
- ug
- ua
- ae
- gb
- us
- uy
- uz
- vu
- va
- ve
- vn
- ye
- zm
- zw
products:
type: array
items:
type: object
properties:
id:
description: Catalog product id
type: string
minLength: 1
variantId:
description: Selected product variant id
type: string
minLength: 1
supplierId:
description: Supplier id for this product
type: string
minLength: 1
hasZTD:
type: boolean
configuration:
type: object
properties:
enableZTD:
type: boolean
enableACE:
type: boolean
required:
- enableZTD
- enableACE
additionalProperties: false
required:
- id
- variantId
- supplierId
- hasZTD
- configuration
additionalProperties: false
shippingAddressType:
anyOf:
- type: string
enum:
- OFFICE
- HOME
- NEW
- type: 'null'
shippingAddress:
description: >-
Delivery address. Take it from `getCompanyAddresses` or
from the employee record — never compose one.
type: object
properties:
name:
anyOf:
- type: string
- type: 'null'
contactName:
anyOf:
- type: string
- type: 'null'
phone:
anyOf:
- type: string
- type: 'null'
street:
type: string
minLength: 1
complement:
anyOf:
- type: string
- type: 'null'
postalCode:
type: string
minLength: 1
city:
type: string
minLength: 1
country:
anyOf:
- type: string
- type: 'null'
countryCode:
anyOf:
- type: string
- type: 'null'
required:
- street
- postalCode
- city
additionalProperties: false
billingProfileId:
anyOf:
- type: string
- type: 'null'
notificationEmails:
type: array
items:
type: string
companyComment:
anyOf:
- type: string
- type: 'null'
appleCareEnterprise:
anyOf:
- type: string
- type: 'null'
companyPurchaseNumber:
anyOf:
- type: string
- type: 'null'
required:
- countryCode
- products
- shippingAddressType
- shippingAddress
- billingProfileId
- notificationEmails
- companyComment
- appleCareEnterprise
- companyPurchaseNumber
additionalProperties: false
- type: 'null'
assignedFromInventory:
anyOf:
- type: object
properties:
deviceIds:
default: []
type: array
items:
type: string
minLength: 1
accessoryIds:
default: []
type: array
items:
type: string
minLength: 1
required:
- deviceIds
- accessoryIds
additionalProperties: false
- type: 'null'
automaticEnrollment:
type: boolean
sendToPersonalEmail:
type: boolean
orderId:
description: >-
The order placed on execute, null until then or when nothing was
bought
anyOf:
- type: string
- type: 'null'
executedAt:
description: When the intent was executed; null while it can still change
anyOf:
- type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
- type: 'null'
createdAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
required:
- id
- taskId
- ticketId
- employeeId
- order
- assignedFromInventory
- automaticEnrollment
- sendToPersonalEmail
- orderId
- executedAt
- createdAt
- updatedAt
additionalProperties: false
order:
description: >-
The order placed for this intent, or null when only stock was handed
over
anyOf:
- type: object
properties:
id:
type: string
reference:
type: string
status:
type: string
required:
- id
- reference
- status
additionalProperties: false
- type: 'null'
required:
- outcome
- intent
- order
additionalProperties: false
securitySchemes:
apikey:
scheme: bearer
bearerFormat: API key
type: http
description: >-
Use your Primo API key in the Authorization header as `Bearer
`.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.