---
title: "Create a macro"
method: POST
path: "/api/macros"
tags: ["Macros"]
---

# Create a macro

`POST /api/macros`

## Request body

- object
  - `external_id` string, nullable — External ID of the macro in a foreign system. This field is not used by Gorgias, feel free to set it to your own value.
  - `name` string, required — The name of the Macro. Tips: choose a name that can be easily searched.
  - `intent` 'discount/request' | 'exchange/request' | 'exchange/status' | 'feedback' | 'order/damaged' | 'order/cancel' | 'order/change' | 'order/wrong' | 'other/no_reply' | 'other/question' | 'other/thanks' | 'product/recommendation' | 'product/question' | 'refund/request' | 'refund/status' | 'return/request' | 'return/status' | 'shipping/change' | 'shipping/delivery-issue' | 'shipping/policy' | 'shipping/status' | 'stock/request' | 'subscription/cancel' | 'subscription/change', nullable — The intention of the macro should be used for.
  - `language` string, nullable — The language of the macro in ISO 639-1 format.
  - `actions` MacroAction[] — A list of [actions](#the-macroaction-object) to be applied on tickets.
    - `arguments` object, required — Parameters of the action. These parameters vary according to the name of the action.
    - `description` string, nullable — Description of what the action does.
    - `name` string, required — The name of the action.
    - `title` string, required — The title of the action.
    - `type` 'system' | 'user' — The type of action.

## Response `201`

The created macro.

- Macro — A macro (canned response) is a list of [actions](#the-macroaction-object) that can be applied to tickets to modify them, and/or reply to them.Macros can be applied manually by agents or automatically by rules. For example, a single macro can add a tag to the ticket, assign an agent to it and send a pre-defined response.
  - `id` integer — ID of the macro.
  - `external_id` string, nullable — External ID of the macro in a foreign system. This field is not used by Gorgias, feel free to set it to your own value.
  - `name` string — The name of the Macro. Tips: choose a name that can be easily searched.
  - `intent` 'discount/request' | 'exchange/request' | 'exchange/status' | 'feedback' | 'order/damaged' | 'order/cancel' | 'order/change' | 'order/wrong' | 'other/no_reply' | 'other/question' | 'other/thanks' | 'product/recommendation' | 'product/question' | 'refund/request' | 'refund/status' | 'return/request' | 'return/status' | 'shipping/change' | 'shipping/delivery-issue' | 'shipping/policy' | 'shipping/status' | 'stock/request' | 'subscription/cancel' | 'subscription/change', nullable — The intention of the macro should be used for.
  - `language` string, nullable — The language of the macro in ISO 639-1 format.
  - `usage` integer — How many times the macro was applied on a ticket.
  - `actions` MacroAction[] — A list of [actions](#the-macroaction-object) to be applied on tickets.
    - `arguments` object, required — Parameters of the action. These parameters vary according to the name of the action.
    - `description` string, nullable — Description of what the action does.
    - `name` string, required — The name of the action.
    - `title` string, required — The title of the action.
    - `type` 'system' | 'user' — The type of action.
  - `created_datetime` string, date-time, nullable — When the macro was created.
  - `updated_datetime` string, date-time, nullable — When the macro was last updated.
  - `archived_datetime` string, date-time, nullable — When the macro was archived.
  - `uri` string — URI of the macro

---

[API](https://skmtc.net/gorgias/apis/gorgias-rest-api.md) · [All operations](https://skmtc.net/gorgias/apis/gorgias-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gorgias/gorgias-rest-api/versions/36f2e31f4e81/schema)