> ## Documentation Index > Fetch the complete documentation index at: https://developer.firstbasedev.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a replacement > Creates a replacement consisting of a return order and a new equipment order ## OpenAPI ````yaml /openapi.json post /api/v1/replacements openapi: 3.1.0 info: title: Firstbase API Specification Beta description: Integration endpoints for Firstbase version: 0.1.0 servers: - url: / description: Default security: - ApiKey: [] tags: - name: Inventory Orders description: Create and manage inventory orders - name: Shipment Notices V1 description: 'Query shipment notice orders (V1: package items expose `inventories` list)' - name: Packages description: '' - name: Categories description: Query available categories for asset creation - name: Catalog description: '' - name: New Joiners description: New joiner provisioning pipeline for the organization - name: Orders description: '' - name: People description: >- Manage the users of Firstbase for your organization. API follows the SCIM standard. externalDocs: url: https://scim.cloud/ - name: People — Lifecycle description: Offboard and reactivate users. - name: Assets description: Manage inventory assets - name: Regions V1 description: Query regions (V1) - name: Warehouses V1 description: Query warehouses (V1) - name: Brands description: Query available brands for asset creation - name: Inventory description: '' - name: Replacements description: Create and manage equipment replacements - name: Offices description: Manage and query office locations for the authenticated organization - name: Returns description: Return and Replacements paths: /api/v1/replacements: post: tags: - Replacements summary: Create a replacement description: >- Creates a replacement consisting of a return order and a new equipment order operationId: createReplacement requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateReplacementRequest' required: true responses: '201': description: Replacement created content: application/json: schema: $ref: '#/components/schemas/PublicAPICreateReplacementResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/PublicApiHttpErrors' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/PublicApiHttpErrors' '409': description: Conflict content: '*/*': schema: $ref: '#/components/schemas/PublicApiHttpErrors' components: schemas: CreateReplacementRequest: type: object description: Request to create a replacement (return + new order) properties: personId: type: string format: uuid description: ID of the person whose equipment is being replaced returnItems: type: array description: Items to return as part of the replacement items: $ref: '#/components/schemas/CreateReturnItemRequest' minItems: 1 order: $ref: '#/components/schemas/ReplacementOrderRequest' description: The replacement order details (new equipment) returnKitAddress: $ref: '#/components/schemas/CreateAddressRequest' description: >- Address for the return kit shipment. Required when requestAddressConfirmation is false (the default). Omit only when requestAddressConfirmation is true, in which case the person is prompted to confirm their address before the kit ships. If omitted and requestAddressConfirmation is false, the order's shipping address is used. officeId: type: string format: uuid description: >- Office ID for office returns. When set, items are returned to the office via SHIPMENT requestAddressConfirmation: type: boolean description: >- Whether to request address confirmation from the person before shipping the return kit isShippingAddressPresentWhenNotConfirming: type: boolean required: - isShippingAddressPresentWhenNotConfirming - order - personId - requestAddressConfirmation - returnItems PublicAPICreateReplacementResponse: type: object description: Response after creating a replacement properties: id: type: string format: uuid description: Replacement ID orderId: type: string format: uuid description: ID of the replacement order (new equipment) returnOrderId: type: string format: uuid description: ID of the return order status: type: string description: Current status of the replacement enum: - SUBMITTED - PROCESSING - COMPLETED - PARTIALLY_COMPLETED - CANCELLED required: - id - status PublicApiHttpErrors: type: object properties: errors: type: array items: $ref: '#/components/schemas/PublicApiError' required: - errors CreateReturnItemRequest: type: object description: An item to include in a return or replacement properties: inventoryId: type: string format: uuid description: >- Inventory ID of the item to return. Required if serialNumber is not provided example: 123e4567-e89b-12d3-a456-426614174000 serialNumber: type: string description: >- Serial number of the item to return. Required if inventoryId is not provided example: SN-12345 returnReason: type: string description: Reason for the return. OFFBOARDING is not allowed via API enum: - OFFBOARDING - UNKNOWN - OFF_CYCLE - DAMAGED - UPGRADE - STANDARD_LIFECYCLE - PRODUCT_CHANGE - OTHER - LOST_BY_WORKER - LOST_BY_PARTNER - FULFILLMENT_ERROR returnReasonComment: type: string description: Additional comment about the return reason returnMethod: type: string description: >- Return method: SHIPMENT (default) or DROP_OFF. DROP_OFF is only allowed for office returns (when officeId is specified). Warehouse returns must use SHIPMENT enum: - DROP_OFF - SHIPMENT - MULTIPLE itad: type: boolean default: false description: >- Whether to elect this item for ITAD (IT Asset Disposition). Only valid for warehouse returns (not office returns) and ITAD-eligible categories (COMPUTER, MOBILE_PHONE, DRAWING_TABLET, TABLET, EXTERNAL_HDD). hasItemIdentifier: type: boolean required: - hasItemIdentifier - returnMethod - returnReason ReplacementOrderRequest: type: object description: Details of the replacement order (new equipment to ship) properties: skus: type: array description: SKUs to order as replacements items: $ref: '#/components/schemas/PublicAPISkuInformation' minItems: 1 shippingAddress: $ref: '#/components/schemas/CreateAddressRequest' description: >- Shipping address for the replacement order. Required when requestAddressConfirmation is false (the default). May be omitted when requestAddressConfirmation is true, in which case the person is prompted to confirm their address before the replacement ships. required: - skus CreateAddressRequest: type: object description: Shipping or return kit address properties: addressLine1: type: string description: Street address line 1 example: 123 minLength: 1 addressLine2: type: string description: Street address line 2 example: Apartment B city: type: string description: City example: San Francisco minLength: 1 state: type: string description: State or province example: California zipCode: type: string description: Postal / ZIP code example: 94158 minLength: 1 country: type: string description: ISO 3166-1 alpha-2 country code example: US minLength: 1 phoneNumber: type: string description: Phone number example: +1-555-123-4567 required: - addressLine1 - city - country - zipCode PublicApiError: type: object properties: detail: type: string description: Human-readable description of the error example: Invalid request source: type: string description: >- Entity or field path that caused the error (for example order, shipmentNotice, or person:email) example: request required: - detail - source PublicAPISkuInformation: type: object description: >- A SKU (product variant) to include in an order, with optional shipping and condition preferences properties: id: type: string format: uuid description: ID of the SKU to order example: 123e4567-e89b-12d3-a456-426614174000 expeditedShippingOption: type: string description: >- Expedited shipping option for this SKU; null means standard shipping applies enum: - EXPEDITED_STANDARD preferredCondition: type: string description: >- Preferred item condition: NEW (new-only) or USED (used preferred). Omit to default to NEW-only preference enum: - NEW - USED required: - id securitySchemes: ApiKey: type: apiKey description: Prefix the value with "ApiKey" to indicate the custom authorization type name: Authorization in: header ````